alepha 0.15.0 → 0.15.2

package/dist/api/users/index.d.ts

@@ -1,19 +1,19 @@
 import * as alepha23 from "alepha";
-import { Alepha, AlephaError, Page, PageQuery, Primitive, Static, StaticEncode, TNull, TObject, TOptional, TSchema, TUnion } from "alepha";
+import { Alepha, AlephaError, FileLike, Json, Page, PageQuery, Primitive, Static, StaticEncode, StreamLike, TNull, TObject, TOptional, TSchema, TUnion } from "alepha";
 import * as alepha_api_notifications0 from "alepha/api/notifications";
 import { VerificationController } from "alepha/api/verifications";
 import * as alepha_server0 from "alepha/server";
 import * as alepha_orm24 from "alepha/orm";
 import { Page as Page$1, Repository } from "alepha/orm";
 import { AuditService } from "alepha/api/audits";
-import * as alepha_logger5 from "alepha/logger";
+import * as alepha_logger6 from "alepha/logger";
 import * as alepha_bucket0 from "alepha/bucket";
 import * as alepha_server_links0 from "alepha/server/links";
 import { OAuth2Profile, ServerAuthProvider, WithLinkFn, WithLoginFn } from "alepha/server/auth";
 import * as alepha_cache0 from "alepha/cache";
 import { DateTime, DateTimeProvider } from "alepha/datetime";
 import { CryptoProvider, IssuerPrimitive, IssuerPrimitiveOptions, UserAccount } from "alepha/security";
-import { FileSystemProvider } from "alepha/file";
+import { Readable } from "node:stream";
 import { FileController } from "alepha/api/files";
 import "drizzle-orm/d1";
 import * as drizzle_orm0 from "drizzle-orm";
@@ -83,114 +83,114 @@ type TObjectUpdate<T extends TObject> = TObject<{ [K in keyof T["properties"]]:
 //#region ../../src/orm/primitives/$entity.d.ts
 interface EntityPrimitiveOptions<T extends TObject, Keys = keyof Static<T>> {
   /**
-       * The database table name that will be created for this entity.
-       * If not provided, name will be inferred from the $repository variable name.
-       */
+   * The database table name that will be created for this entity.
+   * If not provided, name will be inferred from the $repository variable name.
+   */
   name: string;
   /**
-       * TypeBox schema defining the table structure and column types.
-       */
+   * TypeBox schema defining the table structure and column types.
+   */
   schema: T;
   /**
-       * Database indexes to create for query optimization.
-       */
+   * Database indexes to create for query optimization.
+   */
   indexes?: (Keys | {
     /**
-             * Single column to index.
-             */
+     * Single column to index.
+     */
     column: Keys;
     /**
-             * Whether this should be a unique index (enforces uniqueness constraint).
-             */
+     * Whether this should be a unique index (enforces uniqueness constraint).
+     */
     unique?: boolean;
     /**
-             * Custom name for the index. If not provided, generates name automatically.
-             */
+     * Custom name for the index. If not provided, generates name automatically.
+     */
     name?: string;
   } | {
     /**
-             * Multiple columns for composite index (order matters for query optimization).
-             */
+     * Multiple columns for composite index (order matters for query optimization).
+     */
     columns: Keys[];
     /**
-             * Whether this should be a unique index (enforces uniqueness constraint).
-             */
+     * Whether this should be a unique index (enforces uniqueness constraint).
+     */
     unique?: boolean;
     /**
-             * Custom name for the index. If not provided, generates name automatically.
-             */
+     * Custom name for the index. If not provided, generates name automatically.
+     */
     name?: string;
   })[];
   /**
-       * Foreign key constraints to maintain referential integrity.
-       */
+   * Foreign key constraints to maintain referential integrity.
+   */
   foreignKeys?: Array<{
     /**
-             * Optional name for the foreign key constraint.
-             */
+     * Optional name for the foreign key constraint.
+     */
     name?: string;
     /**
-             * Local columns that reference the foreign table.
-             */
+     * Local columns that reference the foreign table.
+     */
     columns: Array<keyof Static<T>>;
     /**
-             * Referenced columns in the foreign table.
-             * Must be EntityColumn references from other entities.
-             */
+     * Referenced columns in the foreign table.
+     * Must be EntityColumn references from other entities.
+     */
     foreignColumns: Array<() => EntityColumn<any>>;
   }>;
   /**
-       * Additional table constraints for data validation.
-       *
-       * Constraints enforce business rules at the database level, providing
-       * an additional layer of data integrity beyond application validation.
-       *
-       * **Constraint Types**:
-       * - **Unique constraints**: Prevent duplicate values across columns
-       * - **Check constraints**: Enforce custom validation rules with SQL expressions
-       *
-       * @example
-       * ```ts
-       * constraints: [
-       *   {
-       *     name: "unique_user_email",
-       *     columns: ["email"],
-       *     unique: true
-       *   },
-       *   {
-       *     name: "valid_age_range",
-       *     columns: ["age"],
-       *     check: sql`age >= 0 AND age <= 150`
-       *   },
-       *   {
-       *     name: "unique_user_username_per_tenant",
-       *     columns: ["tenantId", "username"],
-       *     unique: true
-       *   }
-       * ]
-       * ```
-       */
+   * Additional table constraints for data validation.
+   *
+   * Constraints enforce business rules at the database level, providing
+   * an additional layer of data integrity beyond application validation.
+   *
+   * **Constraint Types**:
+   * - **Unique constraints**: Prevent duplicate values across columns
+   * - **Check constraints**: Enforce custom validation rules with SQL expressions
+   *
+   * @example
+   * ```ts
+   * constraints: [
+   *   {
+   *     name: "unique_user_email",
+   *     columns: ["email"],
+   *     unique: true
+   *   },
+   *   {
+   *     name: "valid_age_range",
+   *     columns: ["age"],
+   *     check: sql`age >= 0 AND age <= 150`
+   *   },
+   *   {
+   *     name: "unique_user_username_per_tenant",
+   *     columns: ["tenantId", "username"],
+   *     unique: true
+   *   }
+   * ]
+   * ```
+   */
   constraints?: Array<{
     /**
-             * Columns involved in this constraint.
-             */
+     * Columns involved in this constraint.
+     */
     columns: Array<keyof Static<T>>;
     /**
-             * Optional name for the constraint.
-             */
+     * Optional name for the constraint.
+     */
     name?: string;
     /**
-             * Whether this is a unique constraint.
-             */
+     * Whether this is a unique constraint.
+     */
     unique?: boolean | {};
     /**
-             * SQL expression for check constraint validation.
-             */
+     * SQL expression for check constraint validation.
+     */
     check?: SQL;
   }>;
   /**
-       * Advanced Drizzle ORM configuration for complex table setups.
-       */
+   * Advanced Drizzle ORM configuration for complex table setups.
+   */
   config?: (self: BuildExtraConfigColumns<string, FromSchema<T>, "pg">) => PgTableExtraConfigValue[];
 }
 declare class EntityPrimitive<T extends TObject = TObject> {
@@ -244,8 +244,8 @@ type PgSymbols = {
   [PG_REF]: PgRefOptions;
   [PG_ENUM]: PgEnumOptions;
   /**
-       * @deprecated Use `PG_IDENTITY` instead.
-       */
+   * @deprecated Use `PG_IDENTITY` instead.
+   */
   [PG_SERIAL]: {};
 };
 type PgSymbolKeys = keyof PgSymbols;
@@ -278,416 +278,416 @@ declare class DbError extends AlephaError {
 //#region ../../src/orm/interfaces/FilterOperators.d.ts
 interface FilterOperators<TValue> {
   /**
-       * Test that two values are equal.
-       *
-       * Remember that the SQL standard dictates that
-       * two NULL values are not equal, so if you want to test
-       * whether a value is null, you may want to use
-       * `isNull` instead.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select cars made by Ford
-       * db.select().from(cars)
-       *   .where(eq(cars.make, 'Ford'))
-       * ```
-       *
-       * @see isNull for a way to test equality to NULL.
-       */
+   * Test that two values are equal.
+   *
+   * Remember that the SQL standard dictates that
+   * two NULL values are not equal, so if you want to test
+   * whether a value is null, you may want to use
+   * `isNull` instead.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select cars made by Ford
+   * db.select().from(cars)
+   *   .where(eq(cars.make, 'Ford'))
+   * ```
+   *
+   * @see isNull for a way to test equality to NULL.
+   */
   eq?: TValue;
   /**
-       * Test that two values are not equal.
-       *
-       * Remember that the SQL standard dictates that
-       * two NULL values are not equal, so if you want to test
-       * whether a value is not null, you may want to use
-       * `isNotNull` instead.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select cars not made by Ford
-       * db.select().from(cars)
-       *   .where(ne(cars.make, 'Ford'))
-       * ```
-       *
-       * @see isNotNull for a way to test whether a value is not null.
-       */
+   * Test that two values are not equal.
+   *
+   * Remember that the SQL standard dictates that
+   * two NULL values are not equal, so if you want to test
+   * whether a value is not null, you may want to use
+   * `isNotNull` instead.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select cars not made by Ford
+   * db.select().from(cars)
+   *   .where(ne(cars.make, 'Ford'))
+   * ```
+   *
+   * @see isNotNull for a way to test whether a value is not null.
+   */
   ne?: TValue;
   /**
-       * Test that the first expression passed is greater than
-       * the second expression.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select cars made after 2000.
-       * db.select().from(cars)
-       *   .where(gt(cars.year, 2000))
-       * ```
-       *
-       * @see gte for greater-than-or-equal
-       */
+   * Test that the first expression passed is greater than
+   * the second expression.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select cars made after 2000.
+   * db.select().from(cars)
+   *   .where(gt(cars.year, 2000))
+   * ```
+   *
+   * @see gte for greater-than-or-equal
+   */
   gt?: TValue;
   /**
-       * Test that the first expression passed is greater than
-       * or equal to the second expression. Use `gt` to
-       * test whether an expression is strictly greater
-       * than another.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select cars made on or after 2000.
-       * db.select().from(cars)
-       *   .where(gte(cars.year, 2000))
-       * ```
-       *
-       * @see gt for a strictly greater-than condition
-       */
+   * Test that the first expression passed is greater than
+   * or equal to the second expression. Use `gt` to
+   * test whether an expression is strictly greater
+   * than another.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select cars made on or after 2000.
+   * db.select().from(cars)
+   *   .where(gte(cars.year, 2000))
+   * ```
+   *
+   * @see gt for a strictly greater-than condition
+   */
   gte?: TValue;
   /**
-       * Test that the first expression passed is less than
-       * the second expression.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select cars made before 2000.
-       * db.select().from(cars)
-       *   .where(lt(cars.year, 2000))
-       * ```
-       *
-       * @see lte for greater-than-or-equal
-       */
+   * Test that the first expression passed is less than
+   * the second expression.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select cars made before 2000.
+   * db.select().from(cars)
+   *   .where(lt(cars.year, 2000))
+   * ```
+   *
+   * @see lte for greater-than-or-equal
+   */
   lt?: TValue;
   /**
-       * Test that the first expression passed is less than
-       * or equal to the second expression.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select cars made before 2000.
-       * db.select().from(cars)
-       *   .where(lte(cars.year, 2000))
-       * ```
-       *
-       * @see lt for a strictly less-than condition
-       */
+   * Test that the first expression passed is less than
+   * or equal to the second expression.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select cars made before 2000.
+   * db.select().from(cars)
+   *   .where(lte(cars.year, 2000))
+   * ```
+   *
+   * @see lt for a strictly less-than condition
+   */
   lte?: TValue;
   /**
-       * Test whether the first parameter, a column or expression,
-       * has a value from a list passed as the second argument.
-       *
-       * ## Throws
-       *
-       * The argument passed in the second array can't be empty:
-       * if an empty is provided, this method will throw.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select cars made by Ford or GM.
-       * db.select().from(cars)
-       *   .where(inArray(cars.make, ['Ford', 'GM']))
-       * ```
-       *
-       * @see notInArray for the inverse of this test
-       */
+   * Test whether the first parameter, a column or expression,
+   * has a value from a list passed as the second argument.
+   *
+   * ## Throws
+   *
+   * The argument passed in the second array can't be empty:
+   * if an empty is provided, this method will throw.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select cars made by Ford or GM.
+   * db.select().from(cars)
+   *   .where(inArray(cars.make, ['Ford', 'GM']))
+   * ```
+   *
+   * @see notInArray for the inverse of this test
+   */
   inArray?: TValue[];
   /**
-       * Test whether the first parameter, a column or expression,
-       * has a value that is not present in a list passed as the
-       * second argument.
-       *
-       * ## Throws
-       *
-       * The argument passed in the second array can't be empty:
-       * if an empty is provided, this method will throw.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select cars made by any company except Ford or GM.
-       * db.select().from(cars)
-       *   .where(notInArray(cars.make, ['Ford', 'GM']))
-       * ```
-       *
-       * @see inArray for the inverse of this test
-       */
+   * Test whether the first parameter, a column or expression,
+   * has a value that is not present in a list passed as the
+   * second argument.
+   *
+   * ## Throws
+   *
+   * The argument passed in the second array can't be empty:
+   * if an empty is provided, this method will throw.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select cars made by any company except Ford or GM.
+   * db.select().from(cars)
+   *   .where(notInArray(cars.make, ['Ford', 'GM']))
+   * ```
+   *
+   * @see inArray for the inverse of this test
+   */
   notInArray?: TValue[];
   /**
-       * Test whether an expression is not NULL. By the SQL standard,
-       * NULL is neither equal nor not equal to itself, so
-       * it's recommended to use `isNull` and `notIsNull` for
-       * comparisons to NULL.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select cars that have been discontinued.
-       * db.select().from(cars)
-       *   .where(isNotNull(cars.discontinuedAt))
-       * ```
-       *
-       * @see isNull for the inverse of this test
-       */
+   * Test whether an expression is not NULL. By the SQL standard,
+   * NULL is neither equal nor not equal to itself, so
+   * it's recommended to use `isNull` and `notIsNull` for
+   * comparisons to NULL.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select cars that have been discontinued.
+   * db.select().from(cars)
+   *   .where(isNotNull(cars.discontinuedAt))
+   * ```
+   *
+   * @see isNull for the inverse of this test
+   */
   isNotNull?: true;
   /**
-       * Test whether an expression is NULL. By the SQL standard,
-       * NULL is neither equal nor not equal to itself, so
-       * it's recommended to use `isNull` and `notIsNull` for
-       * comparisons to NULL.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select cars that have no discontinuedAt date.
-       * db.select().from(cars)
-       *   .where(isNull(cars.discontinuedAt))
-       * ```
-       *
-       * @see isNotNull for the inverse of this test
-       */
+   * Test whether an expression is NULL. By the SQL standard,
+   * NULL is neither equal nor not equal to itself, so
+   * it's recommended to use `isNull` and `notIsNull` for
+   * comparisons to NULL.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select cars that have no discontinuedAt date.
+   * db.select().from(cars)
+   *   .where(isNull(cars.discontinuedAt))
+   * ```
+   *
+   * @see isNotNull for the inverse of this test
+   */
   isNull?: true;
   /**
-       * Test whether an expression is between two values. This
-       * is an easier way to express range tests, which would be
-       * expressed mathematically as `x <= a <= y` but in SQL
-       * would have to be like `a >= x AND a <= y`.
-       *
-       * Between is inclusive of the endpoints: if `column`
-       * is equal to `min` or `max`, it will be TRUE.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select cars made between 1990 and 2000
-       * db.select().from(cars)
-       *   .where(between(cars.year, 1990, 2000))
-       * ```
-       *
-       * @see notBetween for the inverse of this test
-       */
+   * Test whether an expression is between two values. This
+   * is an easier way to express range tests, which would be
+   * expressed mathematically as `x <= a <= y` but in SQL
+   * would have to be like `a >= x AND a <= y`.
+   *
+   * Between is inclusive of the endpoints: if `column`
+   * is equal to `min` or `max`, it will be TRUE.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select cars made between 1990 and 2000
+   * db.select().from(cars)
+   *   .where(between(cars.year, 1990, 2000))
+   * ```
+   *
+   * @see notBetween for the inverse of this test
+   */
   between?: [number, number];
   /**
-       * Test whether an expression is not between two values.
-       *
-       * This, like `between`, includes its endpoints, so if
-       * the `column` is equal to `min` or `max`, in this case
-       * it will evaluate to FALSE.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Exclude cars made in the 1970s
-       * db.select().from(cars)
-       *   .where(notBetween(cars.year, 1970, 1979))
-       * ```
-       *
-       * @see between for the inverse of this test
-       */
+   * Test whether an expression is not between two values.
+   *
+   * This, like `between`, includes its endpoints, so if
+   * the `column` is equal to `min` or `max`, in this case
+   * it will evaluate to FALSE.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Exclude cars made in the 1970s
+   * db.select().from(cars)
+   *   .where(notBetween(cars.year, 1970, 1979))
+   * ```
+   *
+   * @see between for the inverse of this test
+   */
   notBetween?: [number, number];
   /**
-       * Compare a column to a pattern, which can include `%` and `_`
-       * characters to match multiple variations. Including `%`
-       * in the pattern matches zero or more characters, and including
-       * `_` will match a single character.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select all cars with 'Turbo' in their names.
-       * db.select().from(cars)
-       *   .where(like(cars.name, '%Turbo%'))
-       * ```
-       *
-       * @see ilike for a case-insensitive version of this condition
-       */
+   * Compare a column to a pattern, which can include `%` and `_`
+   * characters to match multiple variations. Including `%`
+   * in the pattern matches zero or more characters, and including
+   * `_` will match a single character.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select all cars with 'Turbo' in their names.
+   * db.select().from(cars)
+   *   .where(like(cars.name, '%Turbo%'))
+   * ```
+   *
+   * @see ilike for a case-insensitive version of this condition
+   */
   like?: string;
   /**
-       * The inverse of like - this tests that a given column
-       * does not match a pattern, which can include `%` and `_`
-       * characters to match multiple variations. Including `%`
-       * in the pattern matches zero or more characters, and including
-       * `_` will match a single character.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select all cars that don't have "ROver" in their name.
-       * db.select().from(cars)
-       *   .where(notLike(cars.name, '%Rover%'))
-       * ```
-       *
-       * @see like for the inverse condition
-       * @see notIlike for a case-insensitive version of this condition
-       */
+   * The inverse of like - this tests that a given column
+   * does not match a pattern, which can include `%` and `_`
+   * characters to match multiple variations. Including `%`
+   * in the pattern matches zero or more characters, and including
+   * `_` will match a single character.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select all cars that don't have "ROver" in their name.
+   * db.select().from(cars)
+   *   .where(notLike(cars.name, '%Rover%'))
+   * ```
+   *
+   * @see like for the inverse condition
+   * @see notIlike for a case-insensitive version of this condition
+   */
   notLike?: string;
   /**
-       * Case-insensitively compare a column to a pattern,
-       * which can include `%` and `_`
-       * characters to match multiple variations. Including `%`
-       * in the pattern matches zero or more characters, and including
-       * `_` will match a single character.
-       *
-       * Unlike like, this performs a case-insensitive comparison.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select all cars with 'Turbo' in their names.
-       * db.select().from(cars)
-       *   .where(ilike(cars.name, '%Turbo%'))
-       * ```
-       *
-       * @see like for a case-sensitive version of this condition
-       */
+   * Case-insensitively compare a column to a pattern,
+   * which can include `%` and `_`
+   * characters to match multiple variations. Including `%`
+   * in the pattern matches zero or more characters, and including
+   * `_` will match a single character.
+   *
+   * Unlike like, this performs a case-insensitive comparison.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select all cars with 'Turbo' in their names.
+   * db.select().from(cars)
+   *   .where(ilike(cars.name, '%Turbo%'))
+   * ```
+   *
+   * @see like for a case-sensitive version of this condition
+   */
   ilike?: string;
   /**
-       * The inverse of ilike - this case-insensitively tests that a given column
-       * does not match a pattern, which can include `%` and `_`
-       * characters to match multiple variations. Including `%`
-       * in the pattern matches zero or more characters, and including
-       * `_` will match a single character.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select all cars that don't have "Rover" in their name.
-       * db.select().from(cars)
-       *   .where(notLike(cars.name, '%Rover%'))
-       * ```
-       *
-       * @see ilike for the inverse condition
-       * @see notLike for a case-sensitive version of this condition
-       */
+   * The inverse of ilike - this case-insensitively tests that a given column
+   * does not match a pattern, which can include `%` and `_`
+   * characters to match multiple variations. Including `%`
+   * in the pattern matches zero or more characters, and including
+   * `_` will match a single character.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select all cars that don't have "Rover" in their name.
+   * db.select().from(cars)
+   *   .where(notLike(cars.name, '%Rover%'))
+   * ```
+   *
+   * @see ilike for the inverse condition
+   * @see notLike for a case-sensitive version of this condition
+   */
   notIlike?: string;
   /**
-       * Syntactic sugar for case-insensitive substring matching.
-       * Automatically wraps the value with `%` wildcards on both sides.
-       *
-       * Equivalent to: `ilike: '%value%'`
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select all cars with "Turbo" anywhere in their name.
-       * db.select().from(cars)
-       *   .where({ name: { contains: 'Turbo' } })
-       * // Same as: .where(ilike(cars.name, '%Turbo%'))
-       * ```
-       *
-       * @see ilike for manual pattern matching
-       * @see startsWith for prefix matching
-       * @see endsWith for suffix matching
-       */
+   * Syntactic sugar for case-insensitive substring matching.
+   * Automatically wraps the value with `%` wildcards on both sides.
+   *
+   * Equivalent to: `ilike: '%value%'`
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select all cars with "Turbo" anywhere in their name.
+   * db.select().from(cars)
+   *   .where({ name: { contains: 'Turbo' } })
+   * // Same as: .where(ilike(cars.name, '%Turbo%'))
+   * ```
+   *
+   * @see ilike for manual pattern matching
+   * @see startsWith for prefix matching
+   * @see endsWith for suffix matching
+   */
   contains?: string;
   /**
-       * Syntactic sugar for case-insensitive prefix matching.
-       * Automatically appends a `%` wildcard to the end of the value.
-       *
-       * Equivalent to: `ilike: 'value%'`
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select all cars whose names start with "Ford".
-       * db.select().from(cars)
-       *   .where({ name: { startsWith: 'Ford' } })
-       * // Same as: .where(ilike(cars.name, 'Ford%'))
-       * ```
-       *
-       * @see ilike for manual pattern matching
-       * @see contains for substring matching
-       * @see endsWith for suffix matching
-       */
+   * Syntactic sugar for case-insensitive prefix matching.
+   * Automatically appends a `%` wildcard to the end of the value.
+   *
+   * Equivalent to: `ilike: 'value%'`
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select all cars whose names start with "Ford".
+   * db.select().from(cars)
+   *   .where({ name: { startsWith: 'Ford' } })
+   * // Same as: .where(ilike(cars.name, 'Ford%'))
+   * ```
+   *
+   * @see ilike for manual pattern matching
+   * @see contains for substring matching
+   * @see endsWith for suffix matching
+   */
   startsWith?: string;
   /**
-       * Syntactic sugar for case-insensitive suffix matching.
-       * Automatically prepends a `%` wildcard to the beginning of the value.
-       *
-       * Equivalent to: `ilike: '%value'`
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select all cars whose names end with "Turbo".
-       * db.select().from(cars)
-       *   .where({ name: { endsWith: 'Turbo' } })
-       * // Same as: .where(ilike(cars.name, '%Turbo'))
-       * ```
-       *
-       * @see ilike for manual pattern matching
-       * @see contains for substring matching
-       * @see startsWith for prefix matching
-       */
+   * Syntactic sugar for case-insensitive suffix matching.
+   * Automatically prepends a `%` wildcard to the beginning of the value.
+   *
+   * Equivalent to: `ilike: '%value'`
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select all cars whose names end with "Turbo".
+   * db.select().from(cars)
+   *   .where({ name: { endsWith: 'Turbo' } })
+   * // Same as: .where(ilike(cars.name, '%Turbo'))
+   * ```
+   *
+   * @see ilike for manual pattern matching
+   * @see contains for substring matching
+   * @see startsWith for prefix matching
+   */
   endsWith?: string;
   /**
-       * Test that a column or expression contains all elements of
-       * the list passed as the second argument.
-       *
-       * ## Throws
-       *
-       * The argument passed in the second array can't be empty:
-       * if an empty is provided, this method will throw.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select posts where its tags contain "Typescript" and "ORM".
-       * db.select().from(posts)
-       *   .where(arrayContains(posts.tags, ['Typescript', 'ORM']))
-       * ```
-       *
-       * @see arrayContained to find if an array contains all elements of a column or expression
-       * @see arrayOverlaps to find if a column or expression contains any elements of an array
-       */
+   * Test that a column or expression contains all elements of
+   * the list passed as the second argument.
+   *
+   * ## Throws
+   *
+   * The argument passed in the second array can't be empty:
+   * if an empty is provided, this method will throw.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select posts where its tags contain "Typescript" and "ORM".
+   * db.select().from(posts)
+   *   .where(arrayContains(posts.tags, ['Typescript', 'ORM']))
+   * ```
+   *
+   * @see arrayContained to find if an array contains all elements of a column or expression
+   * @see arrayOverlaps to find if a column or expression contains any elements of an array
+   */
   arrayContains?: TValue;
   /**
-       * Test that the list passed as the second argument contains
-       * all elements of a column or expression.
-       *
-       * ## Throws
-       *
-       * The argument passed in the second array can't be empty:
-       * if an empty is provided, this method will throw.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select posts where its tags contain "Typescript", "ORM" or both,
-       * // but filtering posts that have additional tags.
-       * db.select().from(posts)
-       *   .where(arrayContained(posts.tags, ['Typescript', 'ORM']))
-       * ```
-       *
-       * @see arrayContains to find if a column or expression contains all elements of an array
-       * @see arrayOverlaps to find if a column or expression contains any elements of an array
-       */
+   * Test that the list passed as the second argument contains
+   * all elements of a column or expression.
+   *
+   * ## Throws
+   *
+   * The argument passed in the second array can't be empty:
+   * if an empty is provided, this method will throw.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select posts where its tags contain "Typescript", "ORM" or both,
+   * // but filtering posts that have additional tags.
+   * db.select().from(posts)
+   *   .where(arrayContained(posts.tags, ['Typescript', 'ORM']))
+   * ```
+   *
+   * @see arrayContains to find if a column or expression contains all elements of an array
+   * @see arrayOverlaps to find if a column or expression contains any elements of an array
+   */
   arrayContained?: TValue;
   /**
-       * Test that a column or expression contains any elements of
-       * the list passed as the second argument.
-       *
-       * ## Throws
-       *
-       * The argument passed in the second array can't be empty:
-       * if an empty is provided, this method will throw.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select posts where its tags contain "Typescript", "ORM" or both.
-       * db.select().from(posts)
-       *   .where(arrayOverlaps(posts.tags, ['Typescript', 'ORM']))
-       * ```
-       *
-       * @see arrayContains to find if a column or expression contains all elements of an array
-       * @see arrayContained to find if an array contains all elements of a column or expression
-       */
+   * Test that a column or expression contains any elements of
+   * the list passed as the second argument.
+   *
+   * ## Throws
+   *
+   * The argument passed in the second array can't be empty:
+   * if an empty is provided, this method will throw.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select posts where its tags contain "Typescript", "ORM" or both.
+   * db.select().from(posts)
+   *   .where(arrayOverlaps(posts.tags, ['Typescript', 'ORM']))
+   * ```
+   *
+   * @see arrayContains to find if a column or expression contains all elements of an array
+   * @see arrayContained to find if an array contains all elements of a column or expression
+   */
   arrayOverlaps?: TValue;
 }
 //#endregion
@@ -746,71 +746,71 @@ type PgQueryWhereOrSQL<T extends TObject, Relations extends PgRelationMap<TObjec
 type PgQueryWhereOperators<T extends TObject> = { [Key in keyof Static<T>]?: FilterOperators<Static<T>[Key]> | Static<T>[Key] };
 type PgQueryWhereConditions<T extends TObject, Relations extends PgRelationMap<TObject> | undefined = undefined> = {
   /**
-       * Combine a list of conditions with the `and` operator. Conditions
-       * that are equal `undefined` are automatically ignored.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * db.select().from(cars)
-       *   .where(
-       *     and(
-       *       eq(cars.make, 'Volvo'),
-       *       eq(cars.year, 1950),
-       *     )
-       *   )
-       * ```
-       */
+   * Combine a list of conditions with the `and` operator. Conditions
+   * that are equal `undefined` are automatically ignored.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * db.select().from(cars)
+   *   .where(
+   *     and(
+   *       eq(cars.make, 'Volvo'),
+   *       eq(cars.year, 1950),
+   *     )
+   *   )
+   * ```
+   */
   and?: Array<PgQueryWhereOrSQL<T, Relations>>;
   /**
-       * Combine a list of conditions with the `or` operator. Conditions
-       * that are equal `undefined` are automatically ignored.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * db.select().from(cars)
-       *   .where(
-       *     or(
-       *       eq(cars.make, 'GM'),
-       *       eq(cars.make, 'Ford'),
-       *     )
-       *   )
-       * ```
-       */
+   * Combine a list of conditions with the `or` operator. Conditions
+   * that are equal `undefined` are automatically ignored.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * db.select().from(cars)
+   *   .where(
+   *     or(
+   *       eq(cars.make, 'GM'),
+   *       eq(cars.make, 'Ford'),
+   *     )
+   *   )
+   * ```
+   */
   or?: Array<PgQueryWhereOrSQL<T, Relations>>;
   /**
-       * Negate the meaning of an expression using the `not` keyword.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Select cars _not_ made by GM or Ford.
-       * db.select().from(cars)
-       *   .where(not(inArray(cars.make, ['GM', 'Ford'])))
-       * ```
-       */
+   * Negate the meaning of an expression using the `not` keyword.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Select cars _not_ made by GM or Ford.
+   * db.select().from(cars)
+   *   .where(not(inArray(cars.make, ['GM', 'Ford'])))
+   * ```
+   */
   not?: PgQueryWhereOrSQL<T, Relations>;
   /**
-       * Test whether a subquery evaluates to have any rows.
-       *
-       * ## Examples
-       *
-       * ```ts
-       * // Users whose `homeCity` column has a match in a cities
-       * // table.
-       * db
-       *   .select()
-       *   .from(users)
-       *   .where(
-       *     exists(db.select()
-       *       .from(cities)
-       *       .where(eq(users.homeCity, cities.id))),
-       *   );
-       * ```
-       *
-       * @see notExists for the inverse of this test
-       */
+   * Test whether a subquery evaluates to have any rows.
+   *
+   * ## Examples
+   *
+   * ```ts
+   * // Users whose `homeCity` column has a match in a cities
+   * // table.
+   * db
+   *   .select()
+   *   .from(users)
+   *   .where(
+   *     exists(db.select()
+   *       .from(cities)
+   *       .where(eq(users.homeCity, cities.id))),
+   *   );
+   * ```
+   *
+   * @see notExists for the inverse of this test
+   */
   exists?: SQLWrapper;
 };
 type PgQueryWhereRelations<Relations extends PgRelationMap<TObject> | undefined = undefined> = Relations extends PgRelationMap<TObject> ? { [K in keyof Relations]?: PgQueryWhere<Relations[K]["join"]["schema"], Relations[K]["with"]> } : {};
@@ -831,8 +831,8 @@ interface PgAttrField {
 //#region ../../src/orm/primitives/$sequence.d.ts
 interface SequencePrimitiveOptions extends PgSequenceOptions {
   /**
-       * The name of the sequence. If not provided, the property key will be used.
-       */
+   * The name of the sequence. If not provided, the property key will be used.
+   */
   name?: string;
   provider?: DatabaseProvider;
 }
@@ -872,72 +872,72 @@ interface TableConfigBuilders<TConfig> {
  */
 declare abstract class ModelBuilder {
   /**
-       * Build a table from an entity primitive.
-       */
+   * Build a table from an entity primitive.
+   */
   abstract buildTable(entity: EntityPrimitive, options: {
     tables: Map<string, unknown>;
     enums: Map<string, unknown>;
     schema: string;
   }): void;
   /**
-       * Build a sequence from a sequence primitive.
-       */
+   * Build a sequence from a sequence primitive.
+   */
   abstract buildSequence(sequence: SequencePrimitive, options: {
     sequences: Map<string, unknown>;
     schema: string;
   }): void;
   /**
-       * Convert camelCase to snake_case for column names.
-       */
+   * Convert camelCase to snake_case for column names.
+   */
   protected toColumnName(str: string): string;
   /**
-       * Build the table configuration function for any database.
-       * This includes indexes, foreign keys, constraints, and custom config.
-       *
-       * @param entity - The entity primitive
-       * @param builders - Database-specific builder functions
-       * @param tableResolver - Function to resolve entity references to table columns
-       * @param customConfigHandler - Optional handler for custom config
-       */
+   * Build the table configuration function for any database.
+   * This includes indexes, foreign keys, constraints, and custom config.
+   *
+   * @param entity - The entity primitive
+   * @param builders - Database-specific builder functions
+   * @param tableResolver - Function to resolve entity references to table columns
+   * @param customConfigHandler - Optional handler for custom config
+   */
   protected buildTableConfig<TConfig, TSelf>(entity: EntityPrimitive, builders: TableConfigBuilders<TConfig>, tableResolver?: (entityName: string) => any, customConfigHandler?: (config: any, self: TSelf) => TConfig[]): ((self: TSelf) => TConfig[]) | undefined;
 }
 //#endregion
 //#region ../../src/orm/providers/DrizzleKitProvider.d.ts
 declare class DrizzleKitProvider {
-  protected readonly log: alepha_logger5.Logger;
+  protected readonly log: alepha_logger6.Logger;
   protected readonly alepha: Alepha;
   /**
-       * Synchronize database with current schema definitions.
-       *
-       * In development mode, it will generate and execute migrations based on the current state.
-       * In testing mode, it will generate migrations from scratch without applying them.
-       *
-       * Does nothing in production mode, you must handle migrations manually.
-       */
+   * Synchronize database with current schema definitions.
+   *
+   * In development mode, it will generate and execute migrations based on the current state.
+   * In testing mode, it will generate migrations from scratch without applying them.
+   *
+   * Does nothing in production mode, you must handle migrations manually.
+   */
   synchronize(provider: DatabaseProvider): Promise<void>;
   /**
-       * Mostly used for testing purposes. You can generate SQL migration statements without executing them.
-       */
+   * Mostly used for testing purposes. You can generate SQL migration statements without executing them.
+   */
   generateMigration(provider: DatabaseProvider, prevSnapshot?: any): Promise<{
     statements: string[];
     models: Record<string, unknown>;
     snapshot?: any;
   }>;
   /**
-       * Load all tables, enums, sequences, etc. from the provider's repositories.
-       */
+   * Load all tables, enums, sequences, etc. from the provider's repositories.
+   */
   getModels(provider: DatabaseProvider): Record<string, unknown>;
   /**
-       * Load the migration snapshot from the database.
-       */
+   * Load the migration snapshot from the database.
+   */
   protected loadDevMigrations(provider: DatabaseProvider): Promise<DevMigrations | undefined>;
   protected saveDevMigrations(provider: DatabaseProvider, curr: Record<string, any>, devMigrations?: DevMigrations): Promise<void>;
   protected executeStatements(statements: string[], provider: DatabaseProvider, catchErrors?: boolean): Promise<void>;
   protected createSchemaIfNotExists(provider: DatabaseProvider, schemaName: string): Promise<void>;
   /**
-       * Try to load the official Drizzle Kit API.
-       * If not available, fallback to the local kit import.
-       */
+   * Try to load the official Drizzle Kit API.
+   * If not available, fallback to the local kit import.
+   */
   importDrizzleKit(): typeof DrizzleKit;
 }
 declare const devMigrationsSchema: alepha23.TObject<{
@@ -952,7 +952,7 @@ type DevMigrations = Static<typeof devMigrationsSchema>;
 type SQLLike = SQLWrapper | string;
 declare abstract class DatabaseProvider {
   protected readonly alepha: Alepha;
-  protected readonly log: alepha_logger5.Logger;
+  protected readonly log: alepha_logger6.Logger;
   protected abstract readonly builder: ModelBuilder;
   protected abstract readonly kit: DrizzleKitProvider;
   abstract readonly db: PgDatabase<any>;
@@ -970,39 +970,39 @@ declare abstract class DatabaseProvider {
   abstract execute(statement: SQLLike): Promise<Record<string, unknown>[]>;
   run<T extends TObject>(statement: SQLLike, schema: T): Promise<Array<Static<T>>>;
   /**
-       * Get migrations folder path - can be overridden
-       */
+   * Get migrations folder path - can be overridden
+   */
   protected getMigrationsFolder(): string;
   /**
-       * Base migration orchestration - handles environment logic
-       */
+   * Base migration orchestration - handles environment logic
+   */
   migrate(): Promise<void>;
   /**
-       * Production: run migrations from folder
-       */
+   * Production: run migrations from folder
+   */
   protected runProductionMigration(migrationsFolder: string): Promise<void>;
   /**
-       * Test: always synchronize
-       */
+   * Test: always synchronize
+   */
   protected runTestMigration(): Promise<void>;
   /**
-       * Development: default to synchronize (can be overridden)
-       */
+   * Development: default to synchronize (can be overridden)
+   */
   protected runDevelopmentMigration(migrationsFolder: string): Promise<void>;
   /**
-       * Common synchronization with error handling
-       */
+   * Common synchronization with error handling
+   */
   protected synchronizeSchema(): Promise<void>;
   /**
-       * Provider-specific migration execution
-       * MUST be implemented by each provider
-       */
+   * Provider-specific migration execution
+   * MUST be implemented by each provider
+   */
   protected abstract executeMigrations(migrationsFolder: string): Promise<void>;
   /**
-       * For testing purposes, generate a unique schema name.
-       * The schema name will be generated based on the current date and time.
-       * It will be in the format of `test_YYYYMMDD_HHMMSS_randomSuffix`.
-       */
+   * For testing purposes, generate a unique schema name.
+   * The schema name will be generated based on the current date and time.
+   * It will be in the format of `test_YYYYMMDD_HHMMSS_randomSuffix`.
+   */
   protected generateTestSchemaName(): string;
 }
 //#endregion
@@ -1010,8 +1010,8 @@ declare abstract class DatabaseProvider {
 declare class QueryManager {
   protected readonly alepha: Alepha;
   /**
-       * Convert a query object to a SQL query.
-       */
+   * Convert a query object to a SQL query.
+   */
   toSQL(query: PgQueryWhereOrSQL<TObject>, options: {
     schema: TObject;
     col: (key: string) => PgColumn;
@@ -1019,22 +1019,22 @@ declare class QueryManager {
     dialect: "postgresql" | "sqlite";
   }): SQL | undefined;
   /**
-       * Check if an object has any filter operator properties.
-       */
+   * Check if an object has any filter operator properties.
+   */
   protected hasFilterOperatorProperties(obj: any): boolean;
   /**
-       * Map a filter operator to a SQL query.
-       */
+   * Map a filter operator to a SQL query.
+   */
   mapOperatorToSql(operator: FilterOperators<any> | any, column: PgColumn, columnSchema?: TObject, columnName?: string, dialect?: "postgresql" | "sqlite"): SQL | undefined;
   /**
-       * Parse pagination sort string to orderBy format.
-       * Format: "firstName,-lastName" -> [{ column: "firstName", direction: "asc" }, { column: "lastName", direction: "desc" }]
-       * - Columns separated by comma
-       * - Prefix with '-' for DESC direction
-       *
-       * @param sort Pagination sort string
-       * @returns OrderBy array or single object
-       */
+   * Parse pagination sort string to orderBy format.
+   * Format: "firstName,-lastName" -> [{ column: "firstName", direction: "asc" }, { column: "lastName", direction: "desc" }]
+   * - Columns separated by comma
+   * - Prefix with '-' for DESC direction
+   *
+   * @param sort Pagination sort string
+   * @returns OrderBy array or single object
+   */
   parsePaginationSort(sort: string): Array<{
     column: string;
     direction: "asc" | "desc";
@@ -1043,30 +1043,30 @@ declare class QueryManager {
     direction: "asc" | "desc";
   };
   /**
-       * Normalize orderBy parameter to array format.
-       * Supports 3 modes:
-       * 1. String: "name" -> [{ column: "name", direction: "asc" }]
-       * 2. Object: { column: "name", direction: "desc" } -> [{ column: "name", direction: "desc" }]
-       * 3. Array: [{ column: "name" }, { column: "age", direction: "desc" }] -> normalized array
-       *
-       * @param orderBy The orderBy parameter
-       * @returns Normalized array of order by clauses
-       */
+   * Normalize orderBy parameter to array format.
+   * Supports 3 modes:
+   * 1. String: "name" -> [{ column: "name", direction: "asc" }]
+   * 2. Object: { column: "name", direction: "desc" } -> [{ column: "name", direction: "desc" }]
+   * 3. Array: [{ column: "name" }, { column: "age", direction: "desc" }] -> normalized array
+   *
+   * @param orderBy The orderBy parameter
+   * @returns Normalized array of order by clauses
+   */
   normalizeOrderBy(orderBy: any): Array<{
     column: string;
     direction: "asc" | "desc";
   }>;
   /**
-       * Create a pagination object.
-       *
-       * @deprecated Use `createPagination` from alepha instead.
-       * This method now delegates to the framework-level helper.
-       *
-       * @param entities The entities to paginate.
-       * @param limit The limit of the pagination.
-       * @param offset The offset of the pagination.
-       * @param sort Optional sort metadata to include in response.
-       */
+   * Create a pagination object.
+   *
+   * @deprecated Use `createPagination` from alepha instead.
+   * This method now delegates to the framework-level helper.
+   *
+   * @param entities The entities to paginate.
+   * @param limit The limit of the pagination.
+   * @param offset The offset of the pagination.
+   * @param sort Optional sort metadata to include in response.
+   */
   createPagination<T>(entities: T[], limit?: number, offset?: number, sort?: Array<{
     column: string;
     direction: "asc" | "desc";
@@ -1083,20 +1083,20 @@ interface PgJoin {
 //#region ../../src/orm/services/PgRelationManager.d.ts
 declare class PgRelationManager {
   /**
-       * Recursively build joins for the query builder based on the relations map
-       */
+   * Recursively build joins for the query builder based on the relations map
+   */
   buildJoins(provider: DatabaseProvider, builder: PgSelectBase<any, any, any>, joins: Array<PgJoin>, withRelations: PgRelationMap<TObject>, table: PgTableWithColumns<any>, parentKey?: string): void;
   /**
-       * Map a row with its joined relations based on the joins definition
-       */
+   * Map a row with its joined relations based on the joins definition
+   */
   mapRowWithJoins(record: Record<string, unknown>, row: Record<string, unknown>, schema: TObject, joins: PgJoin[], parentKey?: string): Record<string, unknown>;
   /**
-       * Check if all values in an object are null (indicates a left join with no match)
-       */
+   * Check if all values in an object are null (indicates a left join with no match)
+   */
   private isAllNull;
   /**
-       * Build a schema that includes all join properties recursively
-       */
+   * Build a schema that includes all join properties recursively
+   */
   buildSchemaWithJoins(baseSchema: TObject, joins: PgJoin[], parentPath?: string): TObject;
 }
 //#endregion
@@ -1104,217 +1104,218 @@ declare class PgRelationManager {
 declare abstract class Repository$1<T extends TObject> {
   readonly entity: EntityPrimitive<T>;
   readonly provider: DatabaseProvider;
-  protected readonly log: alepha_logger5.Logger;
+  protected readonly log: alepha_logger6.Logger;
   protected readonly relationManager: PgRelationManager;
   protected readonly queryManager: QueryManager;
   protected readonly dateTimeProvider: DateTimeProvider;
   protected readonly alepha: Alepha;
+  static of<T extends TObject>(entity: EntityPrimitive<T>, provider?: typeof DatabaseProvider): new () => Repository$1<T>;
   constructor(entity: EntityPrimitive<T>, provider?: typeof DatabaseProvider);
   /**
-       * Represents the primary key of the table.
-       * - Key is the name of the primary key column.
-       * - Type is the type (TypeBox) of the primary key column.
-       *
-       * ID is mandatory. If the table does not have a primary key, it will throw an error.
-       */
+   * Represents the primary key of the table.
+   * - Key is the name of the primary key column.
+   * - Type is the type (TypeBox) of the primary key column.
+   *
+   * ID is mandatory. If the table does not have a primary key, it will throw an error.
+   */
   get id(): {
     type: TSchema;
     key: keyof T["properties"];
     col: PgColumn;
   };
   /**
-       * Get Drizzle table object.
-       */
+   * Get Drizzle table object.
+   */
   get table(): PgTableWithColumns<SchemaToTableConfig<T>>;
   /**
-       * Get SQL table name. (from Drizzle table object)
-       */
+   * Get SQL table name. (from Drizzle table object)
+   */
   get tableName(): string;
   /**
-       * Getter for the database connection from the database provider.
-       */
+   * Getter for the database connection from the database provider.
+   */
   protected get db(): PgDatabase<any>;
   /**
-       * Execute a SQL query.
-       *
-       * This method allows executing raw SQL queries against the database.
-       * This is by far the easiest way to run custom queries that are not covered by the repository's built-in methods!
-       *
-       * You must use the `sql` tagged template function from Drizzle ORM to create the query. https://orm.drizzle.team/docs/sql
-       *
-       * @example
-       * ```ts
-       * class App {
-       *   repository = $repository({ ... });
-       *   async getAdults() {
-       *     const users = repository.table; // Drizzle table object
-       *     await repository.query(sql`SELECT * FROM ${users} WHERE ${users.age} > ${18}`);
-       *     // or better
-       *     await repository.query((users) => sql`SELECT * FROM ${users} WHERE ${users.age} > ${18}`);
-       *   }
-       * }
-       * ```
-       */
+   * Execute a SQL query.
+   *
+   * This method allows executing raw SQL queries against the database.
+   * This is by far the easiest way to run custom queries that are not covered by the repository's built-in methods!
+   *
+   * You must use the `sql` tagged template function from Drizzle ORM to create the query. https://orm.drizzle.team/docs/sql
+   *
+   * @example
+   * ```ts
+   * class App {
+   *   repository = $repository({ ... });
+   *   async getAdults() {
+   *     const users = repository.table; // Drizzle table object
+   *     await repository.query(sql`SELECT * FROM ${users} WHERE ${users.age} > ${18}`);
+   *     // or better
+   *     await repository.query((users) => sql`SELECT * FROM ${users} WHERE ${users.age} > ${18}`);
+   *   }
+   * }
+   * ```
+   */
   query<R extends TObject = T>(query: SQLLike | ((table: PgTableWithColumns<SchemaToTableConfig<T>>, db: PgDatabase<any>) => SQLLike), schema?: R): Promise<Static<R>[]>;
   /**
-       * Map raw database fields to entity fields. (handles column name differences)
-       */
+   * Map raw database fields to entity fields. (handles column name differences)
+   */
   protected mapRawFieldsToEntity(row: Record<string, unknown>): any;
   /**
-       * Get a Drizzle column from the table by his name.
-       */
+   * Get a Drizzle column from the table by his name.
+   */
   protected col(name: keyof StaticEncode<T>): PgColumn;
   /**
-       * Run a transaction.
-       */
+   * Run a transaction.
+   */
   transaction<T>(transaction: (tx: PgTransaction<any, Record<string, any>, any>) => Promise<T>, config?: PgTransactionConfig): Promise<T>;
   /**
-       * Start a SELECT query on the table.
-       */
+   * Start a SELECT query on the table.
+   */
   protected rawSelect(opts?: StatementOptions): drizzle_orm_pg_core0.PgSelectBase<string, Record<string, PgColumn<drizzle_orm0.ColumnBaseConfig<drizzle_orm0.ColumnDataType, string>, {}, {}>>, "single", Record<string, "not-null">, false, never, {
     [x: string]: unknown;
   }[], {
     [x: string]: PgColumn<drizzle_orm0.ColumnBaseConfig<drizzle_orm0.ColumnDataType, string>, {}, {}>;
   }>;
   /**
-       * Start a SELECT DISTINCT query on the table.
-       */
+   * Start a SELECT DISTINCT query on the table.
+   */
   protected rawSelectDistinct(opts?: StatementOptions, columns?: (keyof Static<T>)[]): drizzle_orm_pg_core0.PgSelectBase<string, Record<string, any>, "partial", Record<string, "not-null">, false, never, {
     [x: string]: any;
   }[], {
     [x: string]: any;
   }>;
   /**
-       * Start an INSERT query on the table.
-       */
+   * Start an INSERT query on the table.
+   */
   protected rawInsert(opts?: StatementOptions): drizzle_orm_pg_core0.PgInsertBuilder<PgTableWithColumns<SchemaToTableConfig<T>>, any, false>;
   /**
-       * Start an UPDATE query on the table.
-       */
+   * Start an UPDATE query on the table.
+   */
   protected rawUpdate(opts?: StatementOptions): drizzle_orm_pg_core0.PgUpdateBuilder<PgTableWithColumns<SchemaToTableConfig<T>>, any>;
   /**
-       * Start a DELETE query on the table.
-       */
+   * Start a DELETE query on the table.
+   */
   protected rawDelete(opts?: StatementOptions): drizzle_orm_pg_core0.PgDeleteBase<PgTableWithColumns<SchemaToTableConfig<T>>, any, undefined, undefined, false, never>;
   /**
-       * Create a Drizzle `select` query based on a JSON query object.
-       *
-       * > This method is the base for `find`, `findOne`, `findById`, and `paginate`.
-       */
+   * Create a Drizzle `select` query based on a JSON query object.
+   *
+   * > This method is the base for `find`, `findOne`, `findById`, and `paginate`.
+   */
   findMany<R extends PgRelationMap<T>>(query?: PgQueryRelations<T, R>, opts?: StatementOptions): Promise<PgStatic<T, R>[]>;
   /**
-       * Find a single entity.
-       */
+   * Find a single entity.
+   */
   findOne<R extends PgRelationMap<T>>(query: Pick<PgQueryRelations<T, R>, "with" | "where">, opts?: StatementOptions): Promise<PgStatic<T, R>>;
   /**
-       * Find entities with pagination.
-       *
-       * It uses the same parameters as `find()`, but adds pagination metadata to the response.
-       *
-       * > Pagination CAN also do a count query to get the total number of elements.
-       */
+   * Find entities with pagination.
+   *
+   * It uses the same parameters as `find()`, but adds pagination metadata to the response.
+   *
+   * > Pagination CAN also do a count query to get the total number of elements.
+   */
   paginate<R extends PgRelationMap<T>>(pagination?: PageQuery, query?: PgQueryRelations<T, R>, opts?: StatementOptions & {
     count?: boolean;
   }): Promise<Page<PgStatic<T, R>>>;
   /**
-       * Find an entity by ID.
-       *
-       * This is a convenience method for `findOne` with a where clause on the primary key.
-       * If you need more complex queries, use `findOne` instead.
-       */
+   * Find an entity by ID.
+   *
+   * This is a convenience method for `findOne` with a where clause on the primary key.
+   * If you need more complex queries, use `findOne` instead.
+   */
   findById(id: string | number, opts?: StatementOptions): Promise<Static<T>>;
   /**
-       * Helper to create a type-safe query object.
-       */
+   * Helper to create a type-safe query object.
+   */
   createQuery(): PgQuery<T>;
   /**
-       * Helper to create a type-safe where clause.
-       */
+   * Helper to create a type-safe where clause.
+   */
   createQueryWhere(): PgQueryWhere<T>;
   /**
-       * Create an entity.
-       *
-       * @param data The entity to create.
-       * @param opts The options for creating the entity.
-       * @returns The ID of the created entity.
-       */
+   * Create an entity.
+   *
+   * @param data The entity to create.
+   * @param opts The options for creating the entity.
+   * @returns The ID of the created entity.
+   */
   create(data: Static<TObjectInsert<T>>, opts?: StatementOptions): Promise<Static<T>>;
   /**
-       * Create many entities.
-       *
-       * Inserts are batched in chunks of 1000 to avoid hitting database limits.
-       *
-       * @param values The entities to create.
-       * @param opts The statement options.
-       * @returns The created entities.
-       */
+   * Create many entities.
+   *
+   * Inserts are batched in chunks of 1000 to avoid hitting database limits.
+   *
+   * @param values The entities to create.
+   * @param opts The statement options.
+   * @returns The created entities.
+   */
   createMany(values: Array<Static<TObjectInsert<T>>>, opts?: StatementOptions & {
     batchSize?: number;
   }): Promise<Static<T>[]>;
   /**
-       * Find an entity and update it.
-       */
-  updateOne(where: PgQueryWhereOrSQL<T>, data: Partial<Static<TObjectUpdate<T>>>, opts?: StatementOptions): Promise<Static<T>>;
-  /**
-       * Save a given entity.
-       *
-       * @example
-       * ```ts
-       * const entity = await repository.findById(1);
-       * entity.name = "New Name"; // update a field
-       * delete entity.description; // delete a field
-       * await repository.save(entity);
-       * ```
-       *
-       * Difference with `updateById/updateOne`:
-       *
-       * - requires the entity to be fetched first (whole object is expected)
-       * - check pg.version() if present -> optimistic locking
-       * - validate entity against schema
-       * - undefined values will be set to null, not ignored!
-       *
-       * @see {@link DbVersionMismatchError}
-       */
+   * Find an entity and update it.
+   */
+  updateOne(where: PgQueryWhereOrSQL<T>, data: WithSQL<Static<TObjectUpdate<T>>>, opts?: StatementOptions): Promise<Static<T>>;
+  /**
+   * Save a given entity.
+   *
+   * @example
+   * ```ts
+   * const entity = await repository.findById(1);
+   * entity.name = "New Name"; // update a field
+   * delete entity.description; // delete a field
+   * await repository.save(entity);
+   * ```
+   *
+   * Difference with `updateById/updateOne`:
+   *
+   * - requires the entity to be fetched first (whole object is expected)
+   * - check pg.version() if present -> optimistic locking
+   * - validate entity against schema
+   * - undefined values will be set to null, not ignored!
+   *
+   * @see {@link DbVersionMismatchError}
+   */
   save(entity: Static<T>, opts?: StatementOptions): Promise<void>;
   /**
-       * Find an entity by ID and update it.
-       */
-  updateById(id: string | number, data: Partial<Static<TObjectUpdate<T>>>, opts?: StatementOptions): Promise<Static<T>>;
+   * Find an entity by ID and update it.
+   */
+  updateById(id: string | number, data: WithSQL<Static<TObjectUpdate<T>>>, opts?: StatementOptions): Promise<Static<T>>;
   /**
-       * Find many entities and update all of them.
-       */
-  updateMany(where: PgQueryWhereOrSQL<T>, data: Partial<Static<TObjectUpdate<T>>>, opts?: StatementOptions): Promise<Array<number | string>>;
+   * Find many entities and update all of them.
+   */
+  updateMany(where: PgQueryWhereOrSQL<T>, data: WithSQL<Static<TObjectUpdate<T>>>, opts?: StatementOptions): Promise<Array<number | string>>;
   /**
-       * Find many and delete all of them.
-       * @returns Array of deleted entity IDs
-       */
+   * Find many and delete all of them.
+   * @returns Array of deleted entity IDs
+   */
   deleteMany(where?: PgQueryWhereOrSQL<T>, opts?: StatementOptions): Promise<Array<number | string>>;
   /**
-       * Delete all entities.
-       * @returns Array of deleted entity IDs
-       */
+   * Delete all entities.
+   * @returns Array of deleted entity IDs
+   */
   clear(opts?: StatementOptions): Promise<Array<number | string>>;
   /**
-       * Delete the given entity.
-       *
-       * You must fetch the entity first in order to delete it.
-       * @returns Array containing the deleted entity ID
-       */
+   * Delete the given entity.
+   *
+   * You must fetch the entity first in order to delete it.
+   * @returns Array containing the deleted entity ID
+   */
   destroy(entity: Static<T>, opts?: StatementOptions): Promise<Array<number | string>>;
   /**
-       * Find an entity and delete it.
-       * @returns Array of deleted entity IDs (should contain at most one ID)
-       */
+   * Find an entity and delete it.
+   * @returns Array of deleted entity IDs (should contain at most one ID)
+   */
   deleteOne(where?: PgQueryWhereOrSQL<T>, opts?: StatementOptions): Promise<Array<number | string>>;
   /**
-       * Find an entity by ID and delete it.
-       * @returns Array containing the deleted entity ID
-       * @throws DbEntityNotFoundError if the entity is not found
-       */
+   * Find an entity by ID and delete it.
+   * @returns Array containing the deleted entity ID
+   * @throws DbEntityNotFoundError if the entity is not found
+   */
   deleteById(id: string | number, opts?: StatementOptions): Promise<Array<number | string>>;
   /**
-       * Count entities.
-       */
+   * Count entities.
+   */
   count(where?: PgQueryWhereOrSQL<T>, opts?: StatementOptions): Promise<number>;
   protected conflictMessagePattern: string;
   protected handleError(error: unknown, message: string): DbError;
@@ -1323,31 +1324,31 @@ declare abstract class Repository$1<T extends TObject> {
   }): PgQueryWhereOrSQL<T>;
   protected deletedAt(): PgAttrField | undefined;
   /**
-       * Convert something to valid Pg Insert Value.
-       */
+   * Convert something to valid Pg Insert Value.
+   */
   protected cast(data: any, insert: boolean): PgInsertValue<PgTableWithColumns<SchemaToTableConfig<T>>>;
   /**
-       * Transform a row from the database into a clean entity.
-       */
+   * Transform a row from the database into a clean entity.
+   */
   protected clean<T extends TObject>(row: Record<string, unknown>, schema: T): Static<T>;
   /**
-       * Clean a row with joins recursively
-       */
+   * Clean a row with joins recursively
+   */
   protected cleanWithJoins<T extends TObject>(row: Record<string, unknown>, schema: T, joins: PgJoin[], parentPath?: string): Static<T>;
   /**
-       * Convert a where clause to SQL.
-       */
+   * Convert a where clause to SQL.
+   */
   protected toSQL(where: PgQueryWhereOrSQL<T>, joins?: PgJoin[]): SQL | undefined;
   /**
-       * Get the where clause for an ID.
-       *
-       * @param id The ID to get the where clause for.
-       * @returns The where clause for the ID.
-       */
+   * Get the where clause for an ID.
+   *
+   * @param id The ID to get the where clause for.
+   * @returns The where clause for the ID.
+   */
   protected getWhereId(id: string | number): PgQueryWhere<T>;
   /**
-       * Find a primary key in the schema.
-       */
+   * Find a primary key in the schema.
+   */
   protected getPrimaryKey(schema: TObject): {
     key: string;
     col: PgColumn<drizzle_orm0.ColumnBaseConfig<drizzle_orm0.ColumnDataType, string>, {}, {}>;
@@ -1359,25 +1360,26 @@ declare abstract class Repository$1<T extends TObject> {
  */
 interface StatementOptions {
   /**
-       * Transaction to use.
-       */
+   * Transaction to use.
+   */
   tx?: PgTransaction<any, Record<string, any>>;
   /**
-       * Lock strength.
-       */
+   * Lock strength.
+   */
   for?: LockStrength | {
     config: LockConfig;
     strength: LockStrength;
   };
   /**
-       * If true, ignore soft delete.
-       */
+   * If true, ignore soft delete.
+   */
   force?: boolean;
   /**
-       * Force the current time.
-       */
+   * Force the current time.
+   */
   now?: DateTime | string;
 }
+type WithSQL<T> = { [P in keyof T]?: T[P] | SQL };
 //#endregion
 //#region ../../src/api/users/entities/identities.d.ts
 declare const identities: alepha_orm24.EntityPrimitive<alepha23.TObject<{
@@ -1449,20 +1451,20 @@ type RealmPrimitive = IssuerPrimitive & WithLinkFn & WithLoginFn;
 declare const $realm: (options?: RealmOptions) => RealmPrimitive;
 interface RealmOptions {
   /**
-       * Secret key for signing tokens.
-       *
-       * If not provided, the secret from the SecurityProvider will be used (usually from the APP_SECRET environment variable).
-       */
+   * Secret key for signing tokens.
+   *
+   * If not provided, the secret from the SecurityProvider will be used (usually from the APP_SECRET environment variable).
+   */
   secret?: string;
   /**
-       * Issuer configuration options.
-       *
-       * It's already pre-configured for user management with admin and user roles.
-       */
+   * Issuer configuration options.
+   *
+   * It's already pre-configured for user management with admin and user roles.
+   */
   issuer?: Partial<IssuerPrimitiveOptions>;
   /**
-       * Override entities.
-       */
+   * Override entities.
+   */
   entities?: {
     users?: Repository<typeof users.schema>;
     identities?: Repository<typeof identities.schema>;
@@ -1474,11 +1476,20 @@ interface RealmOptions {
     google?: true;
     github?: true;
   };
-  modules?: {
-    files?: boolean;
-    audits?: boolean;
-    jobs?: boolean;
-  };
+  /**
+   * Enable API key authentication.
+   *
+   * When enabled, users can create API keys to access protected endpoints
+   * without using JWT tokens. API keys are useful for:
+   * - Programmatic access (CLI tools, scripts)
+   * - Long-lived authentication tokens
+   * - Third-party integrations
+   *
+   * API keys can be passed via:
+   * - Query parameter: `?api_key=ak_xxx`
+   * - Bearer header: `Authorization: Bearer ak_xxx`
+   */
+  apiKeys?: boolean;
 }
 //#endregion
 //#region ../../src/api/users/providers/RealmProvider.d.ts
@@ -1538,11 +1549,10 @@ declare class RealmProvider {
   }>>;
   protected realms: Map<string, Realm>;
   avatars: alepha_bucket0.BucketPrimitive;
-  protected readonly onConfigure: alepha23.HookPrimitive<"configure">;
   register(realmName: string, realmOptions?: RealmOptions): Realm;
   /**
-       * Gets a registered realm by name, auto-creating default if needed.
-       */
+   * Gets a registered realm by name, auto-creating default if needed.
+   */
   getRealm(realmName?: string): Realm;
   identityRepository(realmName?: string): Repository<typeof identities.schema>;
   sessionRepository(realmName?: string): Repository<typeof sessions.schema>;
@@ -1561,7 +1571,7 @@ type IdentityQuery = Static<typeof identityQuerySchema>;
 //#endregion
 //#region ../../src/api/users/services/IdentityService.d.ts
 declare class IdentityService {
-  protected readonly log: alepha_logger5.Logger;
+  protected readonly log: alepha_logger6.Logger;
   protected readonly realmProvider: RealmProvider;
   protected readonly auditService: AuditService;
   identities(userRealmName?: string): alepha_orm24.Repository<alepha23.TObject<{
@@ -1576,16 +1586,16 @@ declare class IdentityService {
     providerData: alepha23.TOptional<alepha23.TRecord<string, alepha23.TAny>>;
   }>>;
   /**
-       * Find identities with pagination and filtering.
-       */
+   * Find identities with pagination and filtering.
+   */
   findIdentities(q?: IdentityQuery, userRealmName?: string): Promise<Page$1<IdentityEntity>>;
   /**
-       * Get an identity by ID.
-       */
+   * Get an identity by ID.
+   */
   getIdentityById(id: string, userRealmName?: string): Promise<IdentityEntity>;
   /**
-       * Delete an identity by ID.
-       */
+   * Delete an identity by ID.
+   */
   deleteIdentity(id: string, userRealmName?: string): Promise<void>;
 }
 //#endregion
@@ -1595,8 +1605,8 @@ declare class AdminIdentityController {
   protected readonly group = "admin:identities";
   protected readonly identityService: IdentityService;
   /**
-       * Find identities with pagination and filtering.
-       */
+   * Find identities with pagination and filtering.
+   */
   readonly findIdentities: alepha_server0.ActionPrimitiveFn<{
     query: alepha23.TObject<{
       page: alepha23.TOptional<alepha23.TInteger>;
@@ -1618,8 +1628,8 @@ declare class AdminIdentityController {
     }>>;
   }>;
   /**
-       * Get an identity by ID.
-       */
+   * Get an identity by ID.
+   */
   readonly getIdentity: alepha_server0.ActionPrimitiveFn<{
     params: alepha23.TObject<{
       id: alepha23.TString;
@@ -1639,8 +1649,8 @@ declare class AdminIdentityController {
     }>;
   }>;
   /**
-       * Delete an identity.
-       */
+   * Delete an identity.
+   */
   readonly deleteIdentity: alepha_server0.ActionPrimitiveFn<{
     params: alepha23.TObject<{
       id: alepha23.TString;
@@ -1667,7 +1677,7 @@ type SessionQuery = Static<typeof sessionQuerySchema>;
 //#endregion
 //#region ../../src/api/users/services/SessionCrudService.d.ts
 declare class SessionCrudService {
-  protected readonly log: alepha_logger5.Logger;
+  protected readonly log: alepha_logger6.Logger;
   protected readonly realmProvider: RealmProvider;
   sessions(userRealmName?: string): alepha_orm24.Repository<alepha23.TObject<{
     id: alepha_orm24.PgAttr<alepha_orm24.PgAttr<alepha23.TString, typeof alepha_orm24.PG_PRIMARY_KEY>, typeof alepha_orm24.PG_DEFAULT>;
@@ -1685,16 +1695,16 @@ declare class SessionCrudService {
     }>>;
   }>>;
   /**
-       * Find sessions with pagination and filtering.
-       */
+   * Find sessions with pagination and filtering.
+   */
   findSessions(q?: SessionQuery, userRealmName?: string): Promise<Page$1<SessionEntity>>;
   /**
-       * Get a session by ID.
-       */
+   * Get a session by ID.
+   */
   getSessionById(id: string, userRealmName?: string): Promise<SessionEntity>;
   /**
-       * Delete a session by ID.
-       */
+   * Delete a session by ID.
+   */
   deleteSession(id: string, userRealmName?: string): Promise<void>;
 }
 //#endregion
@@ -1704,8 +1714,8 @@ declare class AdminSessionController {
   protected readonly group = "admin:sessions";
   protected readonly sessionService: SessionCrudService;
   /**
-       * Find sessions with pagination and filtering.
-       */
+   * Find sessions with pagination and filtering.
+   */
   readonly findSessions: alepha_server0.ActionPrimitiveFn<{
     query: alepha23.TObject<{
       page: alepha23.TOptional<alepha23.TInteger>;
@@ -1731,8 +1741,8 @@ declare class AdminSessionController {
     }>>;
   }>;
   /**
-       * Get a session by ID.
-       */
+   * Get a session by ID.
+   */
   readonly getSession: alepha_server0.ActionPrimitiveFn<{
     params: alepha23.TObject<{
       id: alepha23.TString;
@@ -1757,8 +1767,8 @@ declare class AdminSessionController {
     }>;
   }>;
   /**
-       * Delete a session.
-       */
+   * Delete a session.
+   */
   readonly deleteSession: alepha_server0.ActionPrimitiveFn<{
     params: alepha23.TObject<{
       id: alepha23.TString;
@@ -1849,7 +1859,7 @@ type UserQuery = Static<typeof userQuerySchema>;
 //#endregion
 //#region ../../src/api/users/services/UserService.d.ts
 declare class UserService {
-  protected readonly log: alepha_logger5.Logger;
+  protected readonly log: alepha_logger6.Logger;
   protected readonly verificationController: alepha_server_links0.HttpVirtualClient<VerificationController>;
   protected readonly userNotifications: UserNotifications;
   protected readonly realmProvider: RealmProvider;
@@ -1871,41 +1881,41 @@ declare class UserService {
     emailVerified: alepha_orm24.PgAttr<alepha23.TBoolean, typeof alepha_orm24.PG_DEFAULT>;
   }>>;
   /**
-       * 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").
-       */
+   * 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").
+   */
   requestEmailVerification(email: string, userRealmName?: string, method?: "code" | "link", verifyUrl?: string): Promise<boolean>;
   /**
-       * Verify a user's email using a valid verification token.
-       * Supports both code (6-digit) and link (UUID) verification tokens.
-       */
+   * Verify a user's email using a valid verification token.
+   * Supports both code (6-digit) and link (UUID) verification tokens.
+   */
   verifyEmail(email: string, token: string, userRealmName?: string): Promise<void>;
   /**
-       * Check if an email is verified.
-       */
+   * Check if an email is verified.
+   */
   isEmailVerified(email: string, userRealmName?: string): Promise<boolean>;
   /**
-       * Find users with pagination and filtering.
-       */
+   * Find users with pagination and filtering.
+   */
   findUsers(q?: UserQuery, userRealmName?: string): Promise<Page$1<UserEntity>>;
   /**
-       * Get a user by ID.
-       */
+   * Get a user by ID.
+   */
   getUserById(id: string, userRealmName?: string): Promise<UserEntity>;
   /**
-       * Create a new user.
-       */
+   * Create a new user.
+   */
   createUser(data: CreateUser, userRealmName?: string): Promise<UserEntity>;
   /**
-       * Update an existing user.
-       */
+   * Update an existing user.
+   */
   updateUser(id: string, data: UpdateUser, userRealmName?: string): Promise<UserEntity>;
   /**
-       * Delete a user by ID.
-       */
+   * Delete a user by ID.
+   */
   deleteUser(id: string, userRealmName?: string): Promise<void>;
 }
 //#endregion
@@ -1915,8 +1925,8 @@ declare class AdminUserController {
   protected readonly group = "admin:users";
   protected readonly userService: UserService;
   /**
-       * Find users with pagination and filtering.
-       */
+   * Find users with pagination and filtering.
+   */
   readonly findUsers: alepha_server0.ActionPrimitiveFn<{
     query: alepha23.TObject<{
       page: alepha23.TOptional<alepha23.TInteger>;
@@ -1947,8 +1957,8 @@ declare class AdminUserController {
     }>>;
   }>;
   /**
-       * Get a user by ID.
-       */
+   * Get a user by ID.
+   */
   readonly getUser: alepha_server0.ActionPrimitiveFn<{
     params: alepha23.TObject<{
       id: alepha23.TString;
@@ -1974,8 +1984,8 @@ declare class AdminUserController {
     }>;
   }>;
   /**
-       * Create a new user.
-       */
+   * Create a new user.
+   */
   readonly createUser: alepha_server0.ActionPrimitiveFn<{
     query: alepha23.TObject<{
       userRealmName: alepha23.TOptional<alepha23.TString>;
@@ -2013,8 +2023,8 @@ declare class AdminUserController {
     }>;
   }>;
   /**
-       * Update a user.
-       */
+   * Update a user.
+   */
   readonly updateUser: alepha_server0.ActionPrimitiveFn<{
     params: alepha23.TObject<{
       id: alepha23.TString;
@@ -2050,8 +2060,8 @@ declare class AdminUserController {
     }>;
   }>;
   /**
-       * Delete a user.
-       */
+   * Delete a user.
+   */
   readonly deleteUser: alepha_server0.ActionPrimitiveFn<{
     params: alepha23.TObject<{
       id: alepha23.TString;
@@ -2078,9 +2088,9 @@ declare class RealmController {
   protected readonly realmProvider: RealmProvider;
   protected readonly serverAuthProvider: ServerAuthProvider;
   /**
-       * Get realm configuration settings.
-       * This endpoint is not exposed in the API documentation.
-       */
+   * Get realm configuration settings.
+   * This endpoint is not exposed in the API documentation.
+   */
   readonly getRealmConfig: alepha_server0.ActionPrimitiveFn<{
     query: alepha23.TObject<{
       realmName: alepha23.TOptional<alepha23.TString>;
@@ -2170,7 +2180,7 @@ interface PasswordResetIntent {
   expiresAt: string;
 }
 declare class CredentialService {
-  protected readonly log: alepha_logger5.Logger;
+  protected readonly log: alepha_logger6.Logger;
   protected readonly cryptoProvider: CryptoProvider;
   protected readonly dateTimeProvider: DateTimeProvider;
   protected readonly verificationController: alepha_server_links0.HttpVirtualClient<VerificationController>;
@@ -2221,36 +2231,36 @@ declare class CredentialService {
     providerData: alepha23.TOptional<alepha23.TRecord<string, alepha23.TAny>>;
   }>>;
   /**
-       * Phase 1: Create a password reset intent.
-       *
-       * Validates the email, checks for existing user with credentials,
-       * sends verification code, and stores the intent in cache.
-       *
-       * @param email - User's email address
-       * @param userRealmName - Optional realm name
-       * @returns Intent response with intentId and expiration (always returns for security)
-       */
+   * Phase 1: Create a password reset intent.
+   *
+   * Validates the email, checks for existing user with credentials,
+   * sends verification code, and stores the intent in cache.
+   *
+   * @param email - User's email address
+   * @param userRealmName - Optional realm name
+   * @returns Intent response with intentId and expiration (always returns for security)
+   */
   createPasswordResetIntent(email: string, userRealmName?: string): Promise<PasswordResetIntentResponse>;
   /**
-       * Phase 2: Complete password reset using an intent.
-       *
-       * Validates the verification code, updates the password,
-       * and invalidates all existing sessions.
-       *
-       * @param body - Request body with intentId, code, and newPassword
-       */
+   * Phase 2: Complete password reset using an intent.
+   *
+   * Validates the verification code, updates the password,
+   * and invalidates all existing sessions.
+   *
+   * @param body - Request body with intentId, code, and newPassword
+   */
   completePasswordReset(body: CompletePasswordResetRequest): Promise<void>;
   /**
-       * @deprecated Use createPasswordResetIntent instead
-       */
+   * @deprecated Use createPasswordResetIntent instead
+   */
   requestPasswordReset(email: string, userRealmName?: string): Promise<boolean>;
   /**
-       * @deprecated Use completePasswordReset instead
-       */
+   * @deprecated Use completePasswordReset instead
+   */
   validateResetToken(email: string, token: string, _userRealmName?: string): Promise<string>;
   /**
-       * @deprecated Use completePasswordReset instead
-       */
+   * @deprecated Use completePasswordReset instead
+   */
   resetPassword(email: string, token: string, newPassword: string, userRealmName?: string): Promise<void>;
 }
 //#endregion
@@ -2312,7 +2322,7 @@ interface RegistrationIntent {
   expiresAt: string;
 }
 declare class RegistrationService {
-  protected readonly log: alepha_logger5.Logger;
+  protected readonly log: alepha_logger6.Logger;
   protected readonly dateTimeProvider: DateTimeProvider;
   protected readonly cryptoProvider: CryptoProvider;
   protected readonly verificationController: alepha_server_links0.HttpVirtualClient<VerificationController>;
@@ -2321,38 +2331,38 @@ declare class RegistrationService {
   protected readonly auditService: AuditService;
   protected readonly intentCache: alepha_cache0.CachePrimitiveFn<RegistrationIntent, any[]>;
   /**
-       * Phase 1: Create a registration intent.
-       *
-       * Validates the registration data, checks for existing users,
-       * creates verification sessions, and stores the intent in cache.
-       */
+   * Phase 1: Create a registration intent.
+   *
+   * Validates the registration data, checks for existing users,
+   * creates verification sessions, and stores the intent in cache.
+   */
   createRegistrationIntent(body: RegisterRequest, userRealmName?: string): Promise<RegistrationIntentResponse>;
   /**
-       * Phase 2: Complete registration using an intent.
-       *
-       * Validates all requirements (verification codes, captcha),
-       * creates the user and credentials, and returns the user.
-       */
+   * Phase 2: Complete registration using an intent.
+   *
+   * Validates all requirements (verification codes, captcha),
+   * creates the user and credentials, and returns the user.
+   */
   completeRegistration(body: CompleteRegistrationRequest): Promise<UserEntity>;
   /**
-       * Check if username, email, and phone are available.
-       */
+   * Check if username, email, and phone are available.
+   */
   protected checkUserAvailability(body: Pick<RegisterRequest, "username" | "email" | "phoneNumber">, userRealmName?: string): Promise<void>;
   /**
-       * Send email verification code.
-       */
+   * Send email verification code.
+   */
   protected sendEmailVerification(email: string): Promise<void>;
   /**
-       * Send phone verification code.
-       */
+   * Send phone verification code.
+   */
   protected sendPhoneVerification(phoneNumber: string): Promise<void>;
   /**
-       * Verify email code using verification service.
-       */
+   * Verify email code using verification service.
+   */
   protected verifyEmailCode(email: string, code: string): Promise<void>;
   /**
-       * Verify phone code using verification service.
-       */
+   * Verify phone code using verification service.
+   */
   protected verifyPhoneCode(phoneNumber: string, code: string): Promise<void>;
 }
 //#endregion
@@ -2364,9 +2374,9 @@ declare class UserController {
   protected readonly userService: UserService;
   protected readonly registrationService: RegistrationService;
   /**
-       * Phase 1: Create a registration intent.
-       * Validates data, creates verification sessions, and stores intent in cache.
-       */
+   * Phase 1: Create a registration intent.
+   * Validates data, creates verification sessions, and stores intent in cache.
+   */
   readonly createRegistrationIntent: alepha_server0.ActionPrimitiveFn<{
     body: alepha23.TObject<{
       password: alepha23.TString;
@@ -2389,9 +2399,9 @@ declare class UserController {
     }>;
   }>;
   /**
-       * Phase 2: Complete registration using an intent.
-       * Validates verification codes and creates the user.
-       */
+   * Phase 2: Complete registration using an intent.
+   * Validates verification codes and creates the user.
+   */
   readonly createUserFromIntent: alepha_server0.ActionPrimitiveFn<{
     body: alepha23.TObject<{
       intentId: alepha23.TString;
@@ -2417,9 +2427,9 @@ declare class UserController {
     }>;
   }>;
   /**
-       * Phase 1: Create a password reset intent.
-       * Validates email, sends verification code, and stores intent in cache.
-       */
+   * Phase 1: Create a password reset intent.
+   * Validates email, sends verification code, and stores intent in cache.
+   */
   readonly createPasswordResetIntent: alepha_server0.ActionPrimitiveFn<{
     query: alepha23.TObject<{
       userRealmName: alepha23.TOptional<alepha23.TString>;
@@ -2433,9 +2443,9 @@ declare class UserController {
     }>;
   }>;
   /**
-       * Phase 2: Complete password reset using an intent.
-       * Validates verification code, updates password, and invalidates sessions.
-       */
+   * Phase 2: Complete password reset using an intent.
+   * Validates verification code, updates password, and invalidates sessions.
+   */
   readonly completePasswordReset: alepha_server0.ActionPrimitiveFn<{
     body: alepha23.TObject<{
       intentId: alepha23.TString;
@@ -2449,8 +2459,8 @@ declare class UserController {
     }>;
   }>;
   /**
-       * @deprecated Use createPasswordResetIntent instead
-       */
+   * @deprecated Use createPasswordResetIntent instead
+   */
   requestPasswordReset: alepha_server0.ActionPrimitiveFn<{
     query: alepha23.TObject<{
       userRealmName: alepha23.TOptional<alepha23.TString>;
@@ -2464,8 +2474,8 @@ declare class UserController {
     }>;
   }>;
   /**
-       * @deprecated Use completePasswordReset instead
-       */
+   * @deprecated Use completePasswordReset instead
+   */
   validateResetToken: alepha_server0.ActionPrimitiveFn<{
     query: alepha23.TObject<{
       email: alepha23.TString;
@@ -2478,8 +2488,8 @@ declare class UserController {
     }>;
   }>;
   /**
-       * @deprecated Use completePasswordReset instead
-       */
+   * @deprecated Use completePasswordReset instead
+   */
   resetPassword: alepha_server0.ActionPrimitiveFn<{
     query: alepha23.TObject<{
       userRealmName: alepha23.TOptional<alepha23.TString>;
@@ -2495,11 +2505,11 @@ declare 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.
-       */
+   * 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.
+   */
   requestEmailVerification: alepha_server0.ActionPrimitiveFn<{
     query: alepha23.TObject<{
       userRealmName: alepha23.TOptional<alepha23.TString>;
@@ -2515,9 +2525,9 @@ declare class UserController {
     }>;
   }>;
   /**
-       * Verify email with a valid token.
-       * Updates the user's emailVerified status.
-       */
+   * Verify email with a valid token.
+   * Updates the user's emailVerified status.
+   */
   verifyEmail: alepha_server0.ActionPrimitiveFn<{
     query: alepha23.TObject<{
       userRealmName: alepha23.TOptional<alepha23.TString>;
@@ -2532,8 +2542,8 @@ declare class UserController {
     }>;
   }>;
   /**
-       * Check if an email is verified.
-       */
+   * Check if an email is verified.
+   */
   checkEmailVerification: alepha_server0.ActionPrimitiveFn<{
     query: alepha23.TObject<{
       email: alepha23.TString;
@@ -2660,13 +2670,303 @@ declare const userResourceSchema: alepha23.TObject<{
 }>;
 type UserResource = Static<typeof userResourceSchema>;
 //#endregion
+//#region ../../src/system/providers/FileSystemProvider.d.ts
+/**
+ * Options for creating a file from a URL
+ */
+interface CreateFileFromUrlOptions {
+  /**
+   * The URL to load the file from (file://, http://, or https://)
+   */
+  url: string;
+  /**
+   * The MIME type of the file (optional, will be detected from filename if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (optional, will be extracted from URL if not provided)
+   */
+  name?: string;
+}
+/**
+ * Options for creating a file from a path (URL with file:// scheme)
+ */
+interface CreateFileFromPathOptions {
+  /**
+   * The path to the file on the local filesystem
+   */
+  path: string;
+  /**
+   * The MIME type of the file (optional, will be detected from filename if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (optional, will be extracted from URL if not provided)
+   */
+  name?: string;
+}
+/**
+ * Options for creating a file from a Buffer
+ */
+interface CreateFileFromBufferOptions {
+  /**
+   * The Buffer containing the file data
+   */
+  buffer: Buffer;
+  /**
+   * The MIME type of the file (optional, will be detected from name if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (required for proper content type detection)
+   */
+  name?: string;
+}
+/**
+ * Options for creating a file from a stream
+ */
+interface CreateFileFromStreamOptions {
+  /**
+   * The readable stream containing the file data
+   */
+  stream: StreamLike;
+  /**
+   * The MIME type of the file (optional, will be detected from name if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (required for proper content type detection)
+   */
+  name?: string;
+  /**
+   * The size of the file in bytes (optional)
+   */
+  size?: number;
+}
+/**
+ * Options for creating a file from text content
+ */
+interface CreateFileFromTextOptions {
+  /**
+   * The text content to create the file from
+   */
+  text: string;
+  /**
+   * The MIME type of the file (default: text/plain)
+   */
+  type?: string;
+  /**
+   * The name of the file (default: "file.txt")
+   */
+  name?: string;
+}
+interface CreateFileFromResponseOptions {
+  /**
+   * The Response object containing the file data
+   */
+  response: Response;
+  /**
+   * Override the name (optional, uses filename from Content-Disposition header if not provided)
+   */
+  name?: string;
+  /**
+   * Override the MIME type (optional, uses file.type if not provided)
+   */
+  type?: string;
+}
+/**
+ * Options for creating a file from a Web File object
+ */
+interface CreateFileFromWebFileOptions {
+  /**
+   * The Web File object
+   */
+  file: File;
+  /**
+   * Override the MIME type (optional, uses file.type if not provided)
+   */
+  type?: string;
+  /**
+   * Override the name (optional, uses file.name if not provided)
+   */
+  name?: string;
+  /**
+   * Override the size (optional, uses file.size if not provided)
+   */
+  size?: number;
+}
+/**
+ * Options for creating a file from an ArrayBuffer
+ */
+interface CreateFileFromArrayBufferOptions {
+  /**
+   * The ArrayBuffer containing the file data
+   */
+  arrayBuffer: ArrayBuffer;
+  /**
+   * The MIME type of the file (optional, will be detected from name if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (required for proper content type detection)
+   */
+  name?: string;
+}
+/**
+ * Union type for all createFile options
+ */
+type CreateFileOptions = CreateFileFromUrlOptions | CreateFileFromPathOptions | CreateFileFromBufferOptions | CreateFileFromStreamOptions | CreateFileFromTextOptions | CreateFileFromWebFileOptions | CreateFileFromResponseOptions | CreateFileFromArrayBufferOptions;
+/**
+ * Options for rm (remove) operation
+ */
+interface RmOptions {
+  /**
+   * If true, removes directories and their contents recursively
+   */
+  recursive?: boolean;
+  /**
+   * If true, no error will be thrown if the path does not exist
+   */
+  force?: boolean;
+}
+/**
+ * Options for cp (copy) operation
+ */
+interface CpOptions {
+  /**
+   * If true, copy directories recursively
+   */
+  recursive?: boolean;
+  /**
+   * If true, overwrite existing destination
+   */
+  force?: boolean;
+}
+/**
+ * Options for mkdir operation
+ */
+interface MkdirOptions {
+  /**
+   * If true, creates parent directories as needed
+   */
+  recursive?: boolean;
+  /**
+   * File mode (permission and sticky bits)
+   */
+  mode?: number;
+}
+/**
+ * Options for ls (list) operation
+ */
+interface LsOptions {
+  /**
+   * If true, list contents of directories recursively
+   */
+  recursive?: boolean;
+  /**
+   * If true, include hidden files (starting with .)
+   */
+  hidden?: boolean;
+}
+/**
+ * FileSystem interface providing utilities for working with files.
+ */
+declare abstract class FileSystemProvider {
+  /**
+   * Joins multiple path segments into a single path.
+   *
+   * @param paths - The path segments to join
+   * @returns The joined path
+   */
+  abstract join(...paths: string[]): string;
+  /**
+   * Creates a FileLike object from various sources.
+   *
+   * @param options - Options for creating the file
+   * @returns A FileLike object
+   */
+  abstract createFile(options: CreateFileOptions): FileLike;
+  /**
+   * Removes a file or directory.
+   *
+   * @param path - The path to remove
+   * @param options - Remove options
+   */
+  abstract rm(path: string, options?: RmOptions): Promise<void>;
+  /**
+   * Copies a file or directory.
+   *
+   * @param src - Source path
+   * @param dest - Destination path
+   * @param options - Copy options
+   */
+  abstract cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+  /**
+   * Moves/renames a file or directory.
+   *
+   * @param src - Source path
+   * @param dest - Destination path
+   */
+  abstract mv(src: string, dest: string): Promise<void>;
+  /**
+   * Creates a directory.
+   *
+   * @param path - The directory path to create
+   * @param options - Mkdir options
+   */
+  abstract mkdir(path: string, options?: MkdirOptions): Promise<void>;
+  /**
+   * Lists files in a directory.
+   *
+   * @param path - The directory path to list
+   * @param options - List options
+   * @returns Array of filenames
+   */
+  abstract ls(path: string, options?: LsOptions): Promise<string[]>;
+  /**
+   * Checks if a file or directory exists.
+   *
+   * @param path - The path to check
+   * @returns True if the path exists, false otherwise
+   */
+  abstract exists(path: string): Promise<boolean>;
+  /**
+   * Reads the content of a file.
+   *
+   * @param path - The file path to read
+   * @returns The file content as a Buffer
+   */
+  abstract readFile(path: string): Promise<Buffer>;
+  /**
+   * Writes data to a file.
+   *
+   * @param path - The file path to write to
+   * @param data - The data to write (Buffer or string)
+   */
+  abstract writeFile(path: string, data: Uint8Array | Buffer | string | FileLike): Promise<void>;
+  /**
+   * Reads the content of a file as a string.
+   *
+   * @param path - The file path to read
+   * @returns The file content as a string
+   */
+  abstract readTextFile(path: string): Promise<string>;
+  /**
+   * Reads the content of a file as JSON.
+   *
+   * @param path - The file path to read
+   * @returns The parsed JSON content
+   */
+  abstract readJsonFile<T = unknown>(path: string): Promise<T>;
+}
+//#endregion
 //#region ../../src/api/users/services/SessionService.d.ts
 declare class SessionService {
   protected readonly alepha: Alepha;
   protected readonly fsp: FileSystemProvider;
   protected readonly dateTimeProvider: DateTimeProvider;
   protected readonly cryptoProvider: CryptoProvider;
-  protected readonly log: alepha_logger5.Logger;
+  protected readonly log: alepha_logger6.Logger;
   protected readonly realmProvider: RealmProvider;
   protected readonly fileController: alepha_server_links0.HttpVirtualClient<FileController>;
   protected readonly auditService: AuditService;
@@ -2713,13 +3013,13 @@ declare class SessionService {
     providerData: alepha23.TOptional<alepha23.TRecord<string, alepha23.TAny>>;
   }>>;
   /**
-       * Random delay to prevent timing attacks (50-200ms)
-       * Uses cryptographically secure random number generation
-       */
+   * Random delay to prevent timing attacks (50-200ms)
+   * Uses cryptographically secure random number generation
+   */
   protected randomDelay(): Promise<void>;
   /**
-       * Validate user credentials and return the user if valid.
-       */
+   * Validate user credentials and return the user if valid.
+   */
   login(provider: string, username: string, password: string, userRealmName?: string): Promise<UserEntity>;
   createSession(user: UserAccount, expiresIn: number, userRealmName?: string): Promise<{
     refreshToken: string;
@@ -2810,10 +3110,21 @@ declare class SessionService {
 //#endregion
 //#region ../../src/api/users/index.d.ts
 /**
- * Provides user management API endpoints for Alepha applications.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | epic | stable |
+ *
+ * Complete user management with multi-realm support for multi-tenant applications.
  *
- * This module includes user CRUD operations, authentication endpoints,
- * password reset functionality, and user profile management capabilities.
+ * **Features:**
+ * - User registration, login, and profile management
+ * - Password reset workflows
+ * - Email verification
+ * - Session management with multiple devices
+ * - Identity management (social logins, SSO)
+ * - Multi-realm support for tenant isolation
+ * - Credential management
+ * - Entities: `users`, `identities`, `sessions`
  *
  * @module alepha.api.users
  */