alepha 0.13.1 → 0.13.3

package/src/api-notifications/index.ts

@@ -1,9 +1,7 @@
 import { $module } from "alepha";
 import { NotificationController } from "./controllers/NotificationController.ts";
-import { $notification } from "./descriptors/$notification.ts";
 import { NotificationJobs } from "./jobs/NotificationJobs.ts";
-import { MemorySmsProvider } from "./providers/MemorySmsProvider.ts";
-import { SmsProvider } from "./providers/SmsProvider.ts";
+import { $notification } from "./primitives/$notification.ts";
 import { NotificationQueues } from "./queues/NotificationQueues.ts";
 import { NotificationSenderService } from "./services/NotificationSenderService.ts";
 import {
@@ -14,14 +12,13 @@ import {
 // ---------------------------------------------------------------------------------------------------------------------
 
 export * from "./controllers/NotificationController.ts";
-export * from "./descriptors/$notification.ts";
 export * from "./entities/notifications.ts";
 export * from "./jobs/NotificationJobs.ts";
-export * from "./providers/MemorySmsProvider.ts";
-export * from "./providers/SmsProvider.ts";
+export * from "./primitives/$notification.ts";
 export * from "./queues/NotificationQueues.ts";
 export * from "./schemas/notificationContactPreferencesSchema.ts";
 export * from "./schemas/notificationCreateSchema.ts";
+export * from "./schemas/notificationQuerySchema.ts";
 export * from "./services/NotificationSenderService.ts";
 export * from "./services/NotificationService.ts";
 
@@ -33,27 +30,21 @@ export * from "./services/NotificationService.ts";
  * This module includes notification sending, retrieval, status tracking,
  * and user notification preferences management.
  *
+ * Requires `AlephaSms` module to be loaded for SMS notifications.
+ *
  * @module alepha.api.notifications
  */
 export const AlephaApiNotifications = $module({
   name: "alepha.api.notifications",
-  descriptors: [$notification],
+  primitives: [$notification],
   services: [
     NotificationController,
     NotificationService,
     NotificationSenderService,
     NotificationQueues,
     NotificationJobs,
-    SmsProvider,
-    MemorySmsProvider,
   ],
   register: (alepha) => {
-    alepha.with({
-      optional: true,
-      provide: SmsProvider,
-      use: MemorySmsProvider,
-    });
-
     const env = alepha.parseEnv(notificationServiceEnvSchema);
     if (env.NOTIFICATION_QUEUE) {
       alepha.with(NotificationQueues);

package/src/api-notifications/{descriptors → primitives}/$notification.ts

@@ -1,8 +1,8 @@
 import {
   $inject,
-  createDescriptor,
-  Descriptor,
+  createPrimitive,
   KIND,
+  Primitive,
   type Static,
   type StaticEncode,
   type TObject,
@@ -10,7 +10,7 @@ import {
 import { NotificationService } from "../services/NotificationService.ts";
 
 /**
- * Creates a notification descriptor for managing email/SMS notification templates.
+ * Creates a notification primitive for managing email/SMS notification templates.
  *
  * Provides type-safe, reusable notification templates with multi-language support,
  * variable substitution, and categorization for different notification channels.
@@ -38,12 +38,12 @@ import { NotificationService } from "../services/NotificationService.ts";
  * ```
  */
 export const $notification = <T extends TObject>(
-  options: NotificationDescriptorOptions<T>,
-) => createDescriptor(NotificationDescriptor<T>, options);
+  options: NotificationPrimitiveOptions<T>,
+) => createPrimitive(NotificationPrimitive<T>, options);
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface NotificationDescriptorOptions<T extends TObject>
+export interface NotificationPrimitiveOptions<T extends TObject>
   extends NotificationMessage<T> {
   name?: string;
   description?: string;
@@ -59,8 +59,8 @@ export interface NotificationDescriptorOptions<T extends TObject>
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export class NotificationDescriptor<T extends TObject> extends Descriptor<
-  NotificationDescriptorOptions<T>
+export class NotificationPrimitive<T extends TObject> extends Primitive<
+  NotificationPrimitiveOptions<T>
 > {
   protected readonly notificationService = $inject(NotificationService);
 
@@ -78,12 +78,12 @@ export class NotificationDescriptor<T extends TObject> extends Descriptor<
     }
   }
 
-  public configure(options: Partial<NotificationDescriptorOptions<T>>) {
+  public configure(options: Partial<NotificationPrimitiveOptions<T>>) {
     Object.assign(this.options, options);
   }
 }
 
-$notification[KIND] = NotificationDescriptor;
+$notification[KIND] = NotificationPrimitive;
 
 // ---------------------------------------------------------------------------------------------------------------------
 

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

@@ -0,0 +1,13 @@
+import type { Static } from "alepha";
+import { t } from "alepha";
+import { pageQuerySchema } from "alepha/orm";
+
+export const notificationQuerySchema = t.extend(pageQuerySchema, {
+  type: t.optional(t.enum(["email", "sms"])),
+  template: t.optional(t.string()),
+  contact: t.optional(t.string()),
+  category: t.optional(t.string()),
+  status: t.optional(t.enum(["pending", "sent", "failed"])),
+});
+
+export type NotificationQuery = Static<typeof notificationQuerySchema>;

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

@@ -3,12 +3,12 @@ import { DateTimeProvider } from "alepha/datetime";
 import { EmailProvider } from "alepha/email";
 import { $logger } from "alepha/logger";
 import { $repository } from "alepha/orm";
-import { $notification } from "../descriptors/$notification.ts";
+import { SmsProvider } from "alepha/sms";
 import {
   type NotificationEntity,
   notifications,
 } from "../entities/notifications.ts";
-import { SmsProvider } from "../providers/SmsProvider.ts";
+import { $notification } from "../primitives/$notification.ts";
 
 export class NotificationSenderService {
   protected readonly alepha = $inject(Alepha);
@@ -161,7 +161,7 @@ export class NotificationSenderService {
     const variables = notification.variables || {};
     const contact = notification.contact;
     const template = this.alepha
-      .descriptors($notification)
+      .primitives($notification)
       .find((it) => it.name === notification.template);
 
     if (!template) {

package/src/api-notifications/services/NotificationService.ts

@@ -2,13 +2,17 @@ import { $env, $inject, Alepha, type Static, t } from "alepha";
 import { $batch } from "alepha/batch";
 import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
-import { $repository } from "alepha/orm";
-import { notifications } from "../entities/notifications.ts";
+import { $repository, type Page } from "alepha/orm";
+import {
+  type NotificationEntity,
+  notifications,
+} from "../entities/notifications.ts";
 import { NotificationQueues } from "../queues/NotificationQueues.ts";
 import {
   type NotificationCreate,
   notificationCreateSchema,
 } from "../schemas/notificationCreateSchema.ts";
+import type { NotificationQuery } from "../schemas/notificationQuerySchema.ts";
 import { NotificationSenderService } from "./NotificationSenderService.ts";
 
 export const notificationServiceEnvSchema = t.object({
@@ -65,6 +69,45 @@ export class NotificationService {
     return this.notificationRepository.findOne({ where: { id } });
   }
 
+  public async findNotifications(
+    q: NotificationQuery = {},
+  ): Promise<Page<NotificationEntity>> {
+    this.log.trace("Finding notifications", { query: q });
+    q.sort ??= "-createdAt";
+
+    const where = this.notificationRepository.createQueryWhere();
+
+    if (q.type) {
+      where.type = { eq: q.type };
+    }
+
+    if (q.template) {
+      where.template = { like: `%${q.template}%` };
+    }
+
+    if (q.contact) {
+      where.contact = { like: `%${q.contact}%` };
+    }
+
+    if (q.category) {
+      where.category = { eq: q.category };
+    }
+
+    if (q.status) {
+      if (q.status === "sent") {
+        where.sentAt = { isNotNull: true };
+        where.error = { isNull: true };
+      } else if (q.status === "failed") {
+        where.error = { isNotNull: true };
+      } else if (q.status === "pending") {
+        where.sentAt = { isNull: true };
+        where.error = { isNull: true };
+      }
+    }
+
+    return this.notificationRepository.paginate(q, { where }, { count: true });
+  }
+
   /**
    * Create a new notification.
    */

package/src/api-parameters/index.browser.ts

@@ -0,0 +1,12 @@
+import { $module } from "alepha";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./entities/parameters.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export const AlephaApiParameters = $module({
+  name: "alepha.api.parameters",
+  services: [],
+});

package/src/api-parameters/index.ts

@@ -2,8 +2,8 @@ import { $module } from "alepha";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export * from "./descriptors/$config.ts";
 export * from "./entities/parameters.ts";
+export * from "./primitives/$config.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 

package/src/api-parameters/{descriptors → primitives}/$config.ts

@@ -1,13 +1,8 @@
-import {
-  createDescriptor,
-  Descriptor,
-  type Static,
-  type TObject,
-} from "alepha";
+import { createPrimitive, Primitive, type Static, type TObject } from "alepha";
 import type { UserAccount } from "alepha/security";
 
 /**
- * Creates a configuration parameter descriptor for managing application settings.
+ * Creates a configuration parameter primitive for managing application settings.
  *
  * Provides type-safe, versioned configuration with schema validation, default values,
  * and scheduled activation. Useful for feature flags, system parameters, and runtime settings.
@@ -33,15 +28,15 @@ import type { UserAccount } from "alepha/security";
  * }
  * ```
  */
-export interface ConfigDescriptorOptions<T extends TObject> {
+export interface ConfigPrimitiveOptions<T extends TObject> {
   name?: string;
   description?: string;
   schema: T;
   default: Static<T>;
 }
 
-export class ConfigDescriptor<T extends TObject> extends Descriptor<
-  ConfigDescriptorOptions<T>
+export class ConfigPrimitive<T extends TObject> extends Primitive<
+  ConfigPrimitiveOptions<T>
 > {
   public get name() {
     return this.options.name || this.config.propertyKey;
@@ -78,7 +73,7 @@ export class ConfigDescriptor<T extends TObject> extends Descriptor<
 }
 
 export const $config = <T extends TObject>(
-  options: ConfigDescriptorOptions<T>,
+  options: ConfigPrimitiveOptions<T>,
 ) => {
-  return createDescriptor(ConfigDescriptor<T>, options);
+  return createPrimitive(ConfigPrimitive<T>, options);
 };

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

@@ -60,10 +60,11 @@ export const realmAuthSettingsAtom = $atom({
     }),
   }),
   default: {
+    // for a fresh hello world setup, we accept registration and email login
     registrationAllowed: true,
     emailEnabled: true,
     emailRequired: true,
-    usernameEnabled: true,
+    usernameEnabled: false,
     usernameRequired: false,
     phoneEnabled: false,
     phoneRequired: false,
@@ -72,6 +73,7 @@ export const realmAuthSettingsAtom = $atom({
     resetPasswordAllowed: false,
     firstNameLastNameEnabled: false,
     firstNameLastNameRequired: false,
+    // TODO: not implemented yet
     passwordPolicy: {
       minLength: 8,
       requireUppercase: true,

package/src/api-users/controllers/UserController.ts

@@ -310,6 +310,8 @@ export class UserController {
   /**
    * Request email verification.
    * Generates a verification token using verification service and sends an email to the user.
+   * @param method - The verification method: "code" (default) sends a 6-digit code, "link" sends a clickable verification link.
+   * @param verifyUrl - Required when method is "link". The base URL for the verification link. Token and email will be appended as query params.
    */
   public requestEmailVerification = $action({
     path: "/users/email-verification/request",
@@ -317,6 +319,19 @@ export class UserController {
     schema: {
       query: t.object({
         userRealmName: t.optional(t.string()),
+        method: t.optional(
+          t.enum(["code", "link"], {
+            default: "code",
+            description:
+              'Verification method: "code" sends a 6-digit code, "link" sends a clickable verification link.',
+          }),
+        ),
+        verifyUrl: t.optional(
+          t.string({
+            description:
+              'Base URL for verification link. Required when method is "link". Token and email will be appended as query params.',
+          }),
+        ),
       }),
       body: t.object({
         email: t.email(),
@@ -327,15 +342,20 @@ export class UserController {
       }),
     },
     handler: async ({ body, query }) => {
+      const method = query.method ?? "code";
       await this.userService.requestEmailVerification(
         body.email,
         query.userRealmName,
+        method,
+        query.verifyUrl,
       );
 
       return {
         success: true,
         message:
-          "If an account exists with this email, a verification code has been sent.",
+          method === "link"
+            ? "If an account exists with this email, a verification link has been sent."
+            : "If an account exists with this email, a verification code has been sent.",
       };
     },
   });

package/src/api-users/index.ts

@@ -21,10 +21,10 @@ export * from "./controllers/IdentityController.ts";
 export * from "./controllers/SessionController.ts";
 export * from "./controllers/UserController.ts";
 export * from "./controllers/UserRealmController.ts";
-export * from "./descriptors/$userRealm.ts";
 export * from "./entities/identities.ts";
 export * from "./entities/sessions.ts";
 export * from "./entities/users.ts";
+export * from "./primitives/$userRealm.ts";
 export * from "./providers/UserRealmProvider.ts";
 export * from "./schemas/completePasswordResetRequestSchema.ts";
 export * from "./schemas/completeRegistrationRequestSchema.ts";

package/src/api-users/{descriptors → primitives}/$userRealm.ts

@@ -1,16 +1,17 @@
 import { $context } from "alepha";
+import { AlephaApiFiles } from "alepha/api/files";
 import type { Repository } from "alepha/orm";
 import {
   $realm,
-  type RealmDescriptor,
-  type RealmDescriptorOptions,
+  type RealmPrimitive,
+  type RealmPrimitiveOptions,
   SecurityProvider,
 } from "alepha/security";
 import {
   $authCredentials,
   $authGithub,
   $authGoogle,
-  type AuthDescriptor,
+  type AuthPrimitive,
   type Credentials,
   type LinkAccountOptions,
   type WithLinkFn,
@@ -23,7 +24,7 @@ import { DEFAULT_USER_REALM_NAME, type users } from "../entities/users.ts";
 import { UserRealmProvider } from "../providers/UserRealmProvider.ts";
 import { SessionService } from "../services/SessionService.ts";
 
-export type UserRealmDescriptor = RealmDescriptor & WithLinkFn & WithLoginFn;
+export type UserRealmPrimitive = RealmPrimitive & WithLinkFn & WithLoginFn;
 
 /**
  * Already configured realm for user management.
@@ -41,16 +42,23 @@ export type UserRealmDescriptor = RealmDescriptor & WithLinkFn & WithLoginFn;
 
 export const $userRealm = (
   options: UserRealmOptions = {},
-): UserRealmDescriptor => {
+): UserRealmPrimitive => {
   const { alepha } = $context();
   const sessionService = alepha.inject(SessionService);
   const securityProvider = alepha.inject(SecurityProvider);
   const userRealmProvider = alepha.inject(UserRealmProvider);
   const name = options.realm?.name ?? DEFAULT_USER_REALM_NAME;
 
-  userRealmProvider.register(name, options);
+  const userRealm = userRealmProvider.register(name, options);
 
-  const realm: UserRealmDescriptor = $realm({
+  if (options.modules?.audits) {
+  }
+
+  if (options.modules?.files) {
+    alepha.with(AlephaApiFiles);
+  }
+
+  const realm: UserRealmPrimitive = $realm({
     ...options.realm,
     name,
     secret: options.secret ?? securityProvider.secretKey,
@@ -103,18 +111,28 @@ export const $userRealm = (
       sessionService.login(name, credentials.username, credentials.password);
   };
 
-  if (options.identities) {
-    const identities: Record<string, AuthDescriptor> = {};
-    if (options.identities?.credentials) {
-      identities.credentials = $authCredentials(realm);
+  const identities = options.identities ?? {
+    credentials: true,
+  };
+
+  if (identities) {
+    const auth: Record<string, AuthPrimitive> = {};
+    if (identities.credentials) {
+      auth.credentials = $authCredentials(realm);
+    } else {
+      // if credentials auth is disabled, disable registration as well
+      userRealm.settings.registrationAllowed = false;
     }
-    if (options.identities?.google) {
-      identities.google = $authGoogle(realm);
+
+    if (identities.google) {
+      auth.google = $authGoogle(realm);
     }
-    if (options.identities?.github) {
-      identities.github = $authGithub(realm);
+
+    if (identities.github) {
+      auth.github = $authGithub(realm);
     }
-    alepha.with(() => identities);
+
+    alepha.with(() => auth);
   }
 
   return realm;
@@ -135,7 +153,7 @@ export interface UserRealmOptions {
    *
    * It's already pre-configured for user management with admin and user roles.
    */
-  realm?: Partial<RealmDescriptorOptions>;
+  realm?: Partial<RealmPrimitiveOptions>;
 
   /**
    * Override entities.
@@ -153,4 +171,9 @@ export interface UserRealmOptions {
     google?: true;
     github?: true;
   };
+
+  modules?: {
+    files?: boolean;
+    audits?: boolean;
+  };
 }

package/src/api-users/providers/UserRealmProvider.ts

@@ -40,7 +40,7 @@ export class UserRealmProvider {
   protected readonly onConfigure = $hook({
     on: "configure",
     handler: () => {
-      this.alepha.state.set("alepha.server.security.system.user", {
+      this.alepha.store.set("alepha.server.security.system.user", {
         id: "00000000-0000-0000-0000-000000000000",
         name: "system",
         roles: ["admin"], // TODO: use realm config
@@ -70,6 +70,7 @@ export class UserRealmProvider {
         },
       },
     });
+    return this.getRealm(userRealmName);
   }
 
   /**

package/src/api-users/services/SessionService.ts

@@ -290,6 +290,8 @@ export class SessionService {
       realm: realm.name,
       username: profile.email.split("@")[0],
       email: profile.email,
+      // we trust the OAuth2 provider
+      emailVerified: true,
       roles: ["user"], // TODO: make default roles configurable via realm settings
     });
 

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

@@ -23,12 +23,22 @@ export class UserService {
 
   /**
    * Request email verification for a user.
+   * @param email - The email address to verify.
+   * @param userRealmName - Optional realm name.
+   * @param method - The verification method: "code" (default) or "link".
+   * @param verifyUrl - Base URL for verification link (required when method is "link").
    */
   public async requestEmailVerification(
     email: string,
     userRealmName?: string,
+    method: "code" | "link" = "code",
+    verifyUrl?: string,
   ): Promise<boolean> {
-    this.log.trace("Requesting email verification", { email, userRealmName });
+    this.log.trace("Requesting email verification", {
+      email,
+      userRealmName,
+      method,
+    });
 
     const user = await this.users(userRealmName)
       .findOne({
@@ -54,23 +64,47 @@ export class UserService {
     try {
       const verification =
         await this.verificationController.requestVerificationCode({
-          params: { type: "code" },
+          params: { type: method },
           body: { target: email },
         });
 
-      await this.userNotifications.emailVerification.push({
-        contact: email,
-        variables: {
+      if (method === "link") {
+        // Build verification URL with token
+        const url = new URL(verifyUrl || "/verify-email", "http://localhost");
+        url.searchParams.set("email", email);
+        url.searchParams.set("token", verification.token);
+        const fullVerifyUrl = verifyUrl
+          ? `${verifyUrl}${url.search}`
+          : url.pathname + url.search;
+
+        await this.userNotifications.emailVerificationLink.push({
+          contact: email,
+          variables: {
+            email,
+            verifyUrl: fullVerifyUrl,
+            expiresInMinutes: Math.floor(verification.codeExpiration / 60),
+          },
+        });
+
+        this.log.debug("Email verification link sent", {
           email,
-          code: verification.token,
-          expiresInMinutes: Math.floor(verification.codeExpiration / 60),
-        },
-      });
+          userId: user.id,
+        });
+      } else {
+        await this.userNotifications.emailVerification.push({
+          contact: email,
+          variables: {
+            email,
+            code: verification.token,
+            expiresInMinutes: Math.floor(verification.codeExpiration / 60),
+          },
+        });
 
-      this.log.debug("Email verification code sent", {
-        email,
-        userId: user.id,
-      });
+        this.log.debug("Email verification code sent", {
+          email,
+          userId: user.id,
+        });
+      }
     } catch (error) {
       // Silent fail for security
       this.log.warn("Failed to send email verification", { email, error });
@@ -81,6 +115,7 @@ export class UserService {
 
   /**
    * Verify a user's email using a valid verification token.
+   * Supports both code (6-digit) and link (UUID) verification tokens.
    */
   public async verifyEmail(
     email: string,
@@ -89,13 +124,18 @@ export class UserService {
   ): Promise<void> {
     this.log.trace("Verifying email", { email, userRealmName });
 
+    // Detect verification type based on token format
+    // Codes are 6-digit numbers, links are UUIDs
+    const isCode = /^\d{6}$/.test(token);
+    const type = isCode ? "code" : "link";
+
     const result = await this.verificationController
       .validateVerificationCode({
-        params: { type: "code" },
+        params: { type },
         body: { target: email, token },
       })
       .catch(() => {
-        this.log.warn("Invalid email verification token", { email });
+        this.log.warn("Invalid email verification token", { email, type });
         throw new BadRequestError("Invalid or expired verification token");
       });
 
@@ -112,7 +152,7 @@ export class UserService {
       emailVerified: true,
     });
 
-    this.log.info("Email verified", { email, userId: user.id });
+    this.log.info("Email verified", { email, userId: user.id, type });
   }
 
   /**

package/src/api-verifications/index.browser.ts

@@ -0,0 +1,15 @@
+import { $module } from "alepha";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./entities/verifications.ts";
+export * from "./schemas/requestVerificationCodeResponseSchema.ts";
+export * from "./schemas/validateVerificationCodeResponseSchema.ts";
+export * from "./schemas/verificationTypeEnumSchema.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export const AlephaApiVerification = $module({
+  name: "alepha.api.verifications",
+  services: [],
+});

package/src/api-verifications/index.ts

@@ -6,6 +6,7 @@ import { VerificationService } from "./services/VerificationService.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 export * from "./controllers/VerificationController.ts";
+export * from "./entities/verifications.ts";
 export * from "./schemas/requestVerificationCodeResponseSchema.ts";
 export * from "./schemas/validateVerificationCodeResponseSchema.ts";
 export * from "./schemas/verificationTypeEnumSchema.ts";