alepha 0.15.0 → 0.15.2

package/package.json

@@ -2,7 +2,7 @@
   "name": "alepha",
   "description": "Easy-to-use modern TypeScript framework for building many kind of applications.",
   "author": "Nicolas Foures",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "type": "module",
   "engines": {
     "node": ">=22.0.0"
@@ -19,30 +19,51 @@
   ],
   "dependencies": {
     "@redis/client": "^5.10.0",
-    "cron-schedule": "^6.0.0",
+    "@vitejs/plugin-react": "^5.1.2",
     "dayjs": "^1.11.19",
     "drizzle-kit": "^0.31.8",
     "drizzle-orm": "^0.45.1",
-    "jose": "^6.1.3",
-    "nodemailer": "^7.0.12",
-    "openid-client": "^6.8.1",
+    "nodemailer": "^7.0.13",
     "postgres": "^3.4.8",
-    "prom-client": "^15.1.3",
     "tsx": "^4.21.0",
-    "typebox": "^1.0.78",
+    "typebox": "^1.0.80",
+    "vite": "^7.3.1",
     "vite-bundle-analyzer": "^1.3.2",
     "ws": "^8.19.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.3.13",
     "@electric-sql/pglite": "^0.3.15",
     "@faker-js/faker": "^10.2.0",
-    "@types/node": "^25.0.9",
-    "@types/nodemailer": "^7.0.5",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^25.1.0",
+    "@types/nodemailer": "^7.0.9",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
     "@types/ws": "^8.18.1",
+    "cron-schedule": "^6.0.0",
+    "jose": "^6.1.3",
+    "jsdom": "^27.4.0",
+    "openid-client": "^6.8.1",
+    "prom-client": "^15.1.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "swagger-ui-dist": "^5.31.0",
-    "tsdown": "^0.20.0-beta.3",
-    "vite": "^7.3.1",
-    "vitest": "^4.0.17"
+    "tsdown": "^0.20.1",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "react": "^19",
+    "react-dom": "^19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   },
   "scarfSettings": {
     "enabled": false
@@ -89,6 +110,11 @@
       "import": "./dist/api/jobs/index.js",
       "default": "./dist/api/jobs/index.js"
     },
+    "./api/keys": {
+      "types": "./dist/api/keys/index.d.ts",
+      "import": "./dist/api/keys/index.js",
+      "default": "./dist/api/keys/index.js"
+    },
     "./api/notifications": {
       "types": "./dist/api/notifications/index.d.ts",
       "react-native": "./dist/api/notifications/index.browser.js",
@@ -174,11 +200,6 @@
       "import": "./dist/fake/index.js",
       "default": "./dist/fake/index.js"
     },
-    "./file": {
-      "types": "./dist/file/index.d.ts",
-      "import": "./dist/file/index.js",
-      "default": "./dist/file/index.js"
-    },
     "./lock": {
       "types": "./dist/lock/core/index.d.ts",
       "import": "./dist/lock/core/index.js",
@@ -217,6 +238,47 @@
       "import": "./dist/queue/redis/index.js",
       "default": "./dist/queue/redis/index.js"
     },
+    "./react/auth": {
+      "types": "./dist/react/auth/index.d.ts",
+      "react-native": "./dist/react/auth/index.browser.js",
+      "browser": "./dist/react/auth/index.browser.js",
+      "import": "./dist/react/auth/index.js",
+      "default": "./dist/react/auth/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/core/index.d.ts",
+      "import": "./dist/react/core/index.js",
+      "default": "./dist/react/core/index.js"
+    },
+    "./react/form": {
+      "types": "./dist/react/form/index.d.ts",
+      "import": "./dist/react/form/index.js",
+      "default": "./dist/react/form/index.js"
+    },
+    "./react/head": {
+      "types": "./dist/react/head/index.d.ts",
+      "react-native": "./dist/react/head/index.browser.js",
+      "browser": "./dist/react/head/index.browser.js",
+      "import": "./dist/react/head/index.js",
+      "default": "./dist/react/head/index.js"
+    },
+    "./react/i18n": {
+      "types": "./dist/react/i18n/index.d.ts",
+      "import": "./dist/react/i18n/index.js",
+      "default": "./dist/react/i18n/index.js"
+    },
+    "./react/router": {
+      "types": "./dist/react/router/index.d.ts",
+      "react-native": "./dist/react/router/index.browser.js",
+      "browser": "./dist/react/router/index.browser.js",
+      "import": "./dist/react/router/index.js",
+      "default": "./dist/react/router/index.js"
+    },
+    "./react/websocket": {
+      "types": "./dist/react/websocket/index.d.ts",
+      "import": "./dist/react/websocket/index.js",
+      "default": "./dist/react/websocket/index.js"
+    },
     "./redis": {
       "types": "./dist/redis/index.d.ts",
       "bun": "./src/redis/index.bun.ts",
@@ -333,6 +395,13 @@
       "import": "./dist/sms/index.js",
       "default": "./dist/sms/index.js"
     },
+    "./system": {
+      "types": "./dist/system/index.d.ts",
+      "react-native": "./dist/system/index.browser.js",
+      "browser": "./dist/system/index.browser.js",
+      "import": "./dist/system/index.js",
+      "default": "./dist/system/index.js"
+    },
     "./thread": {
       "types": "./dist/thread/index.d.ts",
       "import": "./dist/thread/index.js",

package/src/api/audits/index.ts

@@ -15,42 +15,19 @@ export * from "./services/AuditService.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides audit logging API endpoints for Alepha applications.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * This module includes:
- * - Audit log CRUD operations
- * - Filtering and searching audit events
- * - Audit statistics and analytics
- * - `$audit` primitive for domain-specific audit types
+ * Audit trail for compliance.
  *
- * @module alepha.api.audits
- *
- * @example
- * ```ts
- * // In your app module
- * import { AlephaApiAudits } from "alepha/api/audits";
- *
- * const App = $module({
- *   name: "app",
- *   services: [AlephaApiAudits, ...],
- * });
+ * **Features:**
+ * - Domain-specific audit types
+ * - Audit event logging
+ * - Filtering and searching
+ * - User action tracking
  *
- * // Create domain-specific audit types
- * class PaymentAudits {
- *   audit = $audit({
- *     type: "payment",
- *     actions: ["create", "refund", "cancel"],
- *   });
- *
- *   async onPaymentCreated(paymentId: string, userId: string) {
- *     await this.audit.log("create", {
- *       userId,
- *       resourceType: "payment",
- *       resourceId: paymentId,
- *     });
- *   }
- * }
- * ```
+ * @module alepha.api.audits
  */
 export const AlephaApiAudits = $module({
   name: "alepha.api.audits",

package/src/api/files/__tests__/$bucket.spec.ts

@@ -7,7 +7,7 @@ import {
   LocalFileStorageProvider,
   MemoryFileStorageProvider,
 } from "alepha/bucket";
-import { FileSystemProvider } from "alepha/file";
+import { FileSystemProvider } from "alepha/system";
 import { describe, expect, it } from "vitest";
 import { AlephaApiFiles } from "../index.ts";
 

package/src/api/files/controllers/AdminFileStatsController.spec.ts

@@ -1,6 +1,6 @@
 import { Alepha } from "alepha";
 import { $bucket } from "alepha/bucket";
-import { FileSystemProvider } from "alepha/file";
+import { FileSystemProvider } from "alepha/system";
 import { describe, expect, it } from "vitest";
 import { AdminFileStatsController, FileService } from "../index.ts";
 

package/src/api/files/controllers/FileController.spec.ts

@@ -1,7 +1,7 @@
 import { Alepha } from "alepha";
 import { $bucket } from "alepha/bucket";
 import { DateTimeProvider } from "alepha/datetime";
-import { FileSystemProvider } from "alepha/file";
+import { FileSystemProvider } from "alepha/system";
 import { describe, expect, it } from "vitest";
 import { FileController, FileService } from "../index.ts";
 

package/src/api/files/index.ts

@@ -49,10 +49,17 @@ declare module "alepha/bucket" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides file management API endpoints for Alepha applications.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * This module includes file upload, download, storage management,
- * and file metadata operations.
+ * File management endpoints.
+ *
+ * **Features:**
+ * - Upload/download endpoints
+ * - File metadata storage
+ * - TTL-based expiration
+ * - Storage statistics
  *
  * @module alepha.api.files
  */

package/src/api/files/jobs/FileJobs.spec.ts

@@ -1,6 +1,6 @@
 import { Alepha } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
-import { FileSystemProvider } from "alepha/file";
+import { FileSystemProvider } from "alepha/system";
 import { describe, expect, it } from "vitest";
 import { FileJobs, FileService } from "../index.ts";
 

package/src/api/files/services/FileService.spec.ts

@@ -6,7 +6,7 @@ import {
   LocalFileStorageProvider,
   MemoryFileStorageProvider,
 } from "alepha/bucket";
-import { FileSystemProvider } from "alepha/file";
+import { FileSystemProvider } from "alepha/system";
 import { describe, expect, it } from "vitest";
 import { AlephaApiFiles, FileController } from "../index.ts";
 

package/src/api/jobs/index.ts

@@ -17,10 +17,17 @@ export * from "./services/JobService.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides job management API endpoints for Alepha applications.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * This module includes job queue operations, job status monitoring,
- * and background task management capabilities.
+ * Job execution monitoring.
+ *
+ * **Features:**
+ * - Job definitions for tracking
+ * - Job status tracking
+ * - Execution history
+ * - Retry management
  *
  * @module alepha.api.jobs
  */

package/src/api/keys/controllers/AdminApiKeyController.ts

@@ -0,0 +1,75 @@
+import { $inject, t } from "alepha";
+import { $action, okSchema } from "alepha/server";
+import { adminApiKeyQuerySchema } from "../schemas/adminApiKeyQuerySchema.ts";
+import { adminApiKeyResourceSchema } from "../schemas/adminApiKeyResourceSchema.ts";
+import { ApiKeyService } from "../services/ApiKeyService.ts";
+
+/**
+ * REST API controller for admin API key management.
+ * Admins can list, view, and revoke any API key.
+ */
+export class AdminApiKeyController {
+  protected readonly url = "/admin/api-keys";
+  protected readonly group = "admin:api-keys";
+  protected readonly apiKeyService = $inject(ApiKeyService);
+
+  /**
+   * Find all API keys with optional filtering.
+   */
+  public readonly findApiKeys = $action({
+    path: this.url,
+    group: this.group,
+    secure: true,
+    description: "Find API keys with pagination and filtering",
+    schema: {
+      query: adminApiKeyQuerySchema,
+      response: t.page(adminApiKeyResourceSchema),
+    },
+    handler: ({ query }) => {
+      const { userId, includeRevoked, ...pagination } = query;
+      return this.apiKeyService.findAll({
+        userId,
+        includeRevoked,
+        ...pagination,
+      });
+    },
+  });
+
+  /**
+   * Get an API key by ID.
+   */
+  public readonly getApiKey = $action({
+    path: `${this.url}/:id`,
+    group: this.group,
+    secure: true,
+    description: "Get an API key by ID",
+    schema: {
+      params: t.object({
+        id: t.uuid(),
+      }),
+      response: adminApiKeyResourceSchema,
+    },
+    handler: ({ params }) => this.apiKeyService.getById(params.id),
+  });
+
+  /**
+   * Revoke any API key.
+   */
+  public readonly revokeApiKey = $action({
+    method: "DELETE",
+    path: `${this.url}/:id`,
+    group: this.group,
+    secure: true,
+    description: "Revoke an API key",
+    schema: {
+      params: t.object({
+        id: t.uuid(),
+      }),
+      response: okSchema,
+    },
+    handler: async ({ params }) => {
+      await this.apiKeyService.revokeByAdmin(params.id);
+      return { ok: true, id: params.id };
+    },
+  });
+}

package/src/api/keys/controllers/ApiKeyController.ts

@@ -0,0 +1,103 @@
+import { $inject } from "alepha";
+import { $action } from "alepha/server";
+import { createApiKeyBodySchema } from "../schemas/createApiKeyBodySchema.ts";
+import { createApiKeyResponseSchema } from "../schemas/createApiKeyResponseSchema.ts";
+import { listApiKeyResponseSchema } from "../schemas/listApiKeyResponseSchema.ts";
+import { revokeApiKeyParamsSchema } from "../schemas/revokeApiKeyParamsSchema.ts";
+import { revokeApiKeyResponseSchema } from "../schemas/revokeApiKeyResponseSchema.ts";
+import { ApiKeyService } from "../services/ApiKeyService.ts";
+
+/**
+ * REST API controller for user's own API key management.
+ * Users can create, list, and revoke their own API keys.
+ */
+export class ApiKeyController {
+  protected readonly url = "/api-keys";
+  protected readonly group = "api-keys";
+  protected readonly apiKeyService = $inject(ApiKeyService);
+
+  /**
+   * Create a new API key for the authenticated user.
+   * The token is only returned once upon creation.
+   */
+  public readonly createApiKey = $action({
+    method: "POST",
+    path: this.url,
+    group: this.group,
+    description: "Create a new API key",
+    secure: true,
+    schema: {
+      body: createApiKeyBodySchema,
+      response: createApiKeyResponseSchema,
+    },
+    handler: async (request) => {
+      const { apiKey, token } = await this.apiKeyService.create({
+        userId: request.user.id,
+        name: request.body.name,
+        description: request.body.description,
+        roles: request.user.roles ?? [],
+        expiresAt: request.body.expiresAt
+          ? new Date(request.body.expiresAt)
+          : undefined,
+      });
+
+      return {
+        id: apiKey.id,
+        name: apiKey.name,
+        token,
+        tokenSuffix: apiKey.tokenSuffix,
+        roles: apiKey.roles,
+        createdAt: apiKey.createdAt,
+        expiresAt: apiKey.expiresAt,
+      };
+    },
+  });
+
+  /**
+   * List all active API keys for the authenticated user.
+   * Does not return the actual tokens.
+   */
+  public readonly listApiKeys = $action({
+    path: this.url,
+    group: this.group,
+    description: "List your API keys",
+    secure: true,
+    schema: {
+      response: listApiKeyResponseSchema,
+    },
+    handler: async (request) => {
+      const apiKeys = await this.apiKeyService.list(request.user.id);
+
+      return apiKeys.map((apiKey) => ({
+        id: apiKey.id,
+        name: apiKey.name,
+        tokenPrefix: apiKey.tokenPrefix,
+        tokenSuffix: apiKey.tokenSuffix,
+        roles: apiKey.roles,
+        createdAt: apiKey.createdAt,
+        lastUsedAt: apiKey.lastUsedAt,
+        expiresAt: apiKey.expiresAt,
+        usageCount: apiKey.usageCount,
+      }));
+    },
+  });
+
+  /**
+   * Revoke an API key. Only the owner can revoke their own keys.
+   */
+  public readonly revokeApiKey = $action({
+    method: "DELETE",
+    path: `${this.url}/:id`,
+    group: this.group,
+    description: "Revoke an API key",
+    secure: true,
+    schema: {
+      params: revokeApiKeyParamsSchema,
+      response: revokeApiKeyResponseSchema,
+    },
+    handler: async (request) => {
+      await this.apiKeyService.revoke(request.params.id, request.user.id);
+      return { ok: true };
+    },
+  });
+}

package/src/api/keys/entities/apiKeyEntity.ts

@@ -0,0 +1,41 @@
+import { type Static, t } from "alepha";
+import { $entity, db } from "alepha/orm";
+
+export const apiKeyEntity = $entity({
+  name: "api_keys",
+  schema: t.object({
+    id: db.primaryKey(t.uuid()),
+    createdAt: db.createdAt(),
+    updatedAt: db.updatedAt(),
+
+    // Owner
+    userId: t.uuid(),
+
+    // Key metadata
+    name: t.text({ maxLength: 100 }),
+    description: t.optional(t.text({ maxLength: 500 })),
+
+    // Token (hashed) - internal, not user input
+    tokenHash: t.string({ maxLength: 256 }),
+    tokenPrefix: t.string({ maxLength: 10 }),
+    tokenSuffix: t.string({ maxLength: 8 }),
+
+    // Roles (snapshot from user at creation)
+    roles: db.default(t.array(t.string()), []),
+
+    // Tracking
+    lastUsedAt: t.optional(t.datetime()),
+    lastUsedIp: t.optional(t.string({ maxLength: 45 })),
+    usageCount: db.default(t.integer(), 0),
+
+    // Lifecycle
+    expiresAt: t.optional(t.datetime()),
+    revokedAt: t.optional(t.datetime()),
+  }),
+  indexes: [
+    { columns: ["userId", "name"], unique: true },
+    { columns: ["tokenHash"], unique: true },
+  ],
+});
+
+export type ApiKeyEntity = Static<typeof apiKeyEntity.schema>;

package/src/api/keys/index.ts

@@ -0,0 +1,49 @@
+import { $module } from "alepha";
+import { AdminApiKeyController } from "./controllers/AdminApiKeyController.ts";
+import { ApiKeyController } from "./controllers/ApiKeyController.ts";
+import { ApiKeyService } from "./services/ApiKeyService.ts";
+
+export * from "./controllers/AdminApiKeyController.ts";
+export * from "./controllers/ApiKeyController.ts";
+export * from "./entities/apiKeyEntity.ts";
+export * from "./schemas/adminApiKeyQuerySchema.ts";
+export * from "./schemas/adminApiKeyResourceSchema.ts";
+export * from "./schemas/createApiKeyBodySchema.ts";
+export * from "./schemas/createApiKeyResponseSchema.ts";
+export * from "./schemas/listApiKeyResponseSchema.ts";
+export * from "./schemas/revokeApiKeyParamsSchema.ts";
+export * from "./schemas/revokeApiKeyResponseSchema.ts";
+export * from "./services/ApiKeyService.ts";
+
+/**
+ * | type | quality | stability |
+ * |------|---------|--------------|
+ * | backend | good | experimental |
+ *
+ * API key management module for programmatic access.
+ *
+ * **Features:**
+ * - Create API keys with role snapshots
+ * - List and revoke API keys
+ * - 15-minute validation caching
+ * - Query param (?api_key=) and Bearer header support
+ *
+ * **Integration:**
+ * To enable API key authentication for an issuer, register the resolver:
+ *
+ * ```ts
+ * class MyApp {
+ *   apiKeyService = $inject(ApiKeyService);
+ *   issuer = $issuer({
+ *     secret: env.APP_SECRET,
+ *     resolvers: [this.apiKeyService.createResolver()],
+ *   });
+ * }
+ * ```
+ *
+ * @module alepha.api.keys
+ */
+export const AlephaApiKeys = $module({
+  name: "alepha.api.keys",
+  services: [ApiKeyService, ApiKeyController, AdminApiKeyController],
+});

package/src/api/keys/schemas/adminApiKeyQuerySchema.ts

@@ -0,0 +1,7 @@
+import { t } from "alepha";
+import { pageQuerySchema } from "alepha/orm";
+
+export const adminApiKeyQuerySchema = t.extend(pageQuerySchema, {
+  userId: t.optional(t.uuid()),
+  includeRevoked: t.optional(t.boolean()),
+});

package/src/api/keys/schemas/adminApiKeyResourceSchema.ts

@@ -0,0 +1,17 @@
+import { t } from "alepha";
+
+export const adminApiKeyResourceSchema = t.object({
+  id: t.uuid(),
+  userId: t.uuid(),
+  name: t.string(),
+  description: t.optional(t.string()),
+  tokenPrefix: t.string(),
+  tokenSuffix: t.string(),
+  roles: t.array(t.string()),
+  createdAt: t.datetime(),
+  lastUsedAt: t.optional(t.datetime()),
+  lastUsedIp: t.optional(t.string()),
+  expiresAt: t.optional(t.datetime()),
+  revokedAt: t.optional(t.datetime()),
+  usageCount: t.integer(),
+});

package/src/api/keys/schemas/createApiKeyBodySchema.ts

@@ -0,0 +1,7 @@
+import { t } from "alepha";
+
+export const createApiKeyBodySchema = t.object({
+  name: t.text({ minLength: 1, maxLength: 100 }),
+  description: t.optional(t.text({ maxLength: 500 })),
+  expiresAt: t.optional(t.datetime()),
+});

package/src/api/keys/schemas/createApiKeyResponseSchema.ts

@@ -0,0 +1,11 @@
+import { t } from "alepha";
+
+export const createApiKeyResponseSchema = t.object({
+  id: t.uuid(),
+  name: t.string(),
+  token: t.string(),
+  tokenSuffix: t.string(),
+  roles: t.array(t.string()),
+  createdAt: t.datetime(),
+  expiresAt: t.optional(t.datetime()),
+});

package/src/api/keys/schemas/listApiKeyResponseSchema.ts

@@ -0,0 +1,15 @@
+import { t } from "alepha";
+
+export const listApiKeyItemSchema = t.object({
+  id: t.uuid(),
+  name: t.string(),
+  tokenPrefix: t.string(),
+  tokenSuffix: t.string(),
+  roles: t.array(t.string()),
+  createdAt: t.datetime(),
+  lastUsedAt: t.optional(t.datetime()),
+  expiresAt: t.optional(t.datetime()),
+  usageCount: t.integer(),
+});
+
+export const listApiKeyResponseSchema = t.array(listApiKeyItemSchema);

package/src/api/keys/schemas/revokeApiKeyParamsSchema.ts

@@ -0,0 +1,5 @@
+import { t } from "alepha";
+
+export const revokeApiKeyParamsSchema = t.object({
+  id: t.uuid(),
+});

package/src/api/keys/schemas/revokeApiKeyResponseSchema.ts

@@ -0,0 +1,5 @@
+import { t } from "alepha";
+
+export const revokeApiKeyResponseSchema = t.object({
+  ok: t.boolean(),
+});