adonia 0.1.0

package/registry/api/provider.ts

@@ -0,0 +1,129 @@
+import type { ApplicationService } from '@adonisjs/core/types'
+import { HttpContext } from '@adonisjs/core/http'
+import { BaseSerializer } from '@adonisjs/core/transformers'
+import { type SimplePaginatorMetaKeys } from '@adonisjs/lucid/types/querybuilder'
+import {
+  isApiError,
+  isApiResponse,
+  isPaginatedResponse,
+} from '#modules/api/envelope'
+import type {
+  ApiResponse,
+  ApiResult,
+  PaginatedResponse,
+} from '#modules/types/api'
+
+/**
+ * Custom serializer for API responses that ensures consistent JSON structure
+ * across all API endpoints. Wraps response data in a 'data' property and handles
+ * pagination metadata for Lucid ORM query results.
+ */
+class ApiSerializer extends BaseSerializer<{
+  Wrap: 'data'
+  PaginationMetaData: SimplePaginatorMetaKeys
+}> {
+  /**
+   * Wraps all serialized data under this key in the response object.
+   * Example: { data: [...] } instead of returning raw arrays/objects
+   */
+  wrap: 'data' = 'data'
+
+  /**
+   * Validates and defines pagination metadata structure for paginated responses.
+   * Ensures that pagination info from Lucid queries is properly formatted.
+   *
+   * @throws Error if metadata doesn't match Lucid's pagination structure
+   */
+  definePaginationMetaData(metaData: unknown): SimplePaginatorMetaKeys {
+    if (!this.isLucidPaginatorMetaData(metaData)) {
+      throw new Error(
+        'Invalid pagination metadata. Expected metadata to contain Lucid pagination keys'
+      )
+    }
+    return metaData
+  }
+}
+
+/**
+ * Single instance of ApiSerializer used across the application
+ */
+const serializer = new ApiSerializer()
+
+const serialize = Object.assign(
+  function (this: HttpContext, ...[data, resolver]: Parameters<ApiSerializer['serialize']>) {
+    return serializer.serialize(data, resolver ?? this.containerResolver)
+  },
+  {
+    withoutWrapping(
+      this: HttpContext,
+      ...[data, resolver]: Parameters<ApiSerializer['serializeWithoutWrapping']>
+    ) {
+      return serializer.serializeWithoutWrapping(data, resolver ?? this.containerResolver)
+    },
+  }
+) as ApiSerializer['serialize'] & { withoutWrapping: ApiSerializer['serializeWithoutWrapping'] }
+
+type Respondable =
+  | ApiResponse<unknown>
+  | ApiResult<unknown>
+  | PaginatedResponse<unknown>
+
+/**
+ * Bridges ApiService envelopes to HTTP JSON without double-wrapping `data`.
+ * Serializes the payload via transformers, then restores the shared envelope.
+ */
+export async function respond(this: HttpContext, result: Respondable) {
+  if (isApiError(result)) {
+    this.response.status(result.status ?? 400)
+    return result
+  }
+
+  if (isPaginatedResponse(result)) {
+    const data = await serializer.serializeWithoutWrapping(
+      result.data,
+      this.containerResolver
+    )
+    return {
+      success: true as const,
+      message: result.message,
+      data,
+      meta: result.meta,
+    }
+  }
+
+  if (isApiResponse(result)) {
+    const data = await serializer.serializeWithoutWrapping(
+      result.data,
+      this.containerResolver
+    )
+    return {
+      success: true as const,
+      message: result.message,
+      data,
+    }
+  }
+
+  return result
+}
+
+/**
+ * Registers HTTP helpers used by all API controllers.
+ */
+export default class ApiProvider {
+  constructor(protected app: ApplicationService) {}
+
+  async boot() {
+    HttpContext.instanceProperty('serialize', serialize)
+    HttpContext.instanceProperty('respond', respond)
+  }
+}
+
+/**
+ * Module augmentation for HttpContext API helpers.
+ */
+declare module '@adonisjs/core/http' {
+  export interface HttpContext {
+    serialize: typeof serialize
+    respond: typeof respond
+  }
+}

package/registry/api/service.ts

@@ -0,0 +1,88 @@
+/*
+ * Domain base for feature modules.
+ *
+ * Envelope helpers (prepareResponse / prepareError / preparePaginatedResponse)
+ * are for controllers and hosts — domain services under modules/ return DTOs
+ * and throw ApiException instead of wrapping results.
+ *
+ * HTTP serialization lives on HttpContext via the api provider (ctx.respond).
+ */
+import emitter from '@adonisjs/core/services/emitter'
+import logger from '@adonisjs/core/services/logger'
+import config from '@adonisjs/core/services/config'
+import type { EventsList } from '@adonisjs/core/types'
+import { ModelsTypes, ApiTypes } from '#modules/types'
+import { prepareError } from '#modules/api/envelope'
+
+export default class ApiService {
+  namespace: ModelsTypes.NameSpace = null
+
+  resolveConfig() {
+    if (!this.namespace) {
+      return null
+    }
+    return config.get<ModelsTypes.ModuleActionConfig>(`modules.${this.namespace}`)
+  }
+
+  /**
+   * Build a success envelope. Prefer calling this from controllers/hosts,
+   * not from domain services under modules/.
+   */
+  prepareResponse<T>(data: T, message: string | null = null): ApiTypes.ApiResponse<T> {
+    return {
+      data,
+      message,
+      success: true,
+    }
+  }
+
+  prepareError(message: string, status?: number): ApiTypes.ApiResult<never> {
+    return prepareError(message, status)
+  }
+
+  /**
+   * Build a paginated success envelope with meta. Controllers/hosts only.
+   */
+  preparePaginatedResponse<T>(
+    data: T[],
+    total: number,
+    params: ApiTypes.PaginationParams = {}
+  ): ApiTypes.PaginatedResponse<T> {
+    const page = params.page ?? 1
+    const pageSize = params.pageSize ?? data.length
+    return {
+      data,
+      message: null,
+      success: true,
+      meta: {
+        total,
+        page,
+        pageSize,
+        totalPages: pageSize > 0 ? Math.ceil(total / pageSize) : 0,
+      },
+    }
+  }
+
+  /**
+   * Emit a typed domain event when listed in config/modules.ts.
+   * Types come from EventsList augmentations imported by each feature module.
+   */
+  public async emitSafe<K extends keyof EventsList>(
+    eventName: K,
+    payload: EventsList[K]
+  ): Promise<void> {
+    const actionConfig = this.resolveConfig()
+    if (!actionConfig) {
+      logger.warn(`No modules.${this.namespace} config; skipping ${String(eventName)}`)
+      return
+    }
+    if (!actionConfig.emits.includes(eventName as string)) {
+      return
+    }
+    try {
+      await emitter.emit(eventName, payload)
+    } catch (err) {
+      logger.error(`Event emit failed for ${String(eventName)}: %o`, err)
+    }
+  }
+}

package/registry/api/tests/emit_safe.spec.ts

@@ -0,0 +1,107 @@
+import { test } from '@japa/runner'
+import assert from 'node:assert/strict'
+import emitter from '@adonisjs/core/services/emitter'
+import config from '@adonisjs/core/services/config'
+import { AuthService } from '#modules/auth/service'
+import type { User, UserStore } from '#modules/contracts/index'
+import type { PasswordResetStore } from '#modules/auth/contracts/index'
+import '#modules/auth/events'
+
+function makeUser(): User {
+  return {
+    id: 1,
+    email: 'user@test.com',
+    pendingEmail: null,
+    authMethod: 'email',
+    firstName: 'Test',
+    lastName: 'User',
+    avatarKey: null,
+    emailVerifiedAt: new Date(),
+    emailVerificationToken: null,
+  }
+}
+
+function makeUserStore(): UserStore {
+  return {
+    createEmailUser: async () => makeUser(),
+    findOrFail: async () => makeUser(),
+    findByEmail: async () => null,
+    findByEmailOrFail: async () => makeUser(),
+    findByVerificationToken: async () => null,
+    verifyCredentials: async () => makeUser(),
+    verifyPassword: async () => true,
+    save: async (u) => u,
+    updatePassword: async (u) => u,
+    delete: async () => {},
+  }
+}
+
+function makePasswordResetStore(): PasswordResetStore {
+  return {
+    createForUser: async () => ({ id: 1, userId: 1, token: 't', isExpired: false }),
+    findByToken: async () => null,
+    deleteForUser: async () => {},
+    refreshToken: async (r) => r,
+    findUserByReset: async () => makeUser(),
+  }
+}
+
+test.group('ApiService emitSafe', () => {
+  test('emits listed events and skips unlisted ones', async () => {
+    const service = new AuthService(makeUserStore(), makePasswordResetStore())
+    const emitted: string[] = []
+    const originalEmit = emitter.emit.bind(emitter)
+    const originalGet = config.get.bind(config)
+
+    ;(emitter as any).emit = async (event: string, payload: unknown) => {
+      emitted.push(event)
+      return originalEmit(event as any, payload as any)
+    }
+
+    ;(config as any).get = (key: string) => {
+      if (key === 'modules.auth') {
+        return {
+          description: 'test',
+          emits: ['Auth:Logout'],
+        }
+      }
+      return originalGet(key)
+    }
+
+    try {
+      await service.emitSafe('Auth:Logout', null)
+      await service.emitSafe('Auth:Login', { user: makeUser() })
+      assert.deepEqual(emitted, ['Auth:Logout'])
+    } finally {
+      ;(emitter as any).emit = originalEmit
+      ;(config as any).get = originalGet
+    }
+  })
+
+  test('resolves when a listener throws', async () => {
+    const service = new AuthService(makeUserStore(), makePasswordResetStore())
+    const originalEmit = emitter.emit.bind(emitter)
+    const originalGet = config.get.bind(config)
+
+    ;(config as any).get = (key: string) => {
+      if (key === 'modules.auth') {
+        return {
+          description: 'test',
+          emits: ['Auth:Logout'],
+        }
+      }
+      return originalGet(key)
+    }
+
+    ;(emitter as any).emit = async () => {
+      throw new Error('listener boom')
+    }
+
+    try {
+      await service.emitSafe('Auth:Logout', null)
+    } finally {
+      ;(emitter as any).emit = originalEmit
+      ;(config as any).get = originalGet
+    }
+  })
+})

package/registry/api/tests/respond.spec.ts

@@ -0,0 +1,40 @@
+import { test } from '@japa/runner'
+import assert from 'node:assert/strict'
+import type { HttpContext } from '@adonisjs/core/http'
+import { respond } from '#modules/api/provider'
+import { prepareError } from '#modules/api/envelope'
+
+test.group('ctx.respond error status', () => {
+  test('sets HTTP status from ApiErrorBody', async () => {
+    let statusCode = 200
+    const ctx = {
+      response: {
+        status(code: number) {
+          statusCode = code
+          return this
+        },
+      },
+    } as unknown as HttpContext
+
+    const body = prepareError('E_X', 409)
+    const result = await respond.call(ctx, body)
+
+    assert.equal(statusCode, 409)
+    assert.deepEqual(result, { success: false, message: 'E_X', status: 409 })
+  })
+
+  test('defaults to 400 when status is omitted', async () => {
+    let statusCode = 200
+    const ctx = {
+      response: {
+        status(code: number) {
+          statusCode = code
+          return this
+        },
+      },
+    } as unknown as HttpContext
+
+    await respond.call(ctx, prepareError('E_X'))
+    assert.equal(statusCode, 400)
+  })
+})

package/registry/auth/contracts/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Auth module contracts.
+ * Shared User / UserStore: #modules/contracts
+ */
+export type {
+  AuthPasswordReset,
+  LoginCredentials,
+  LoginResult,
+  UpdatePasswordInput,
+  TokenDuration,
+  SessionResult,
+} from './types.ts'
+
+export type { PasswordResetStore } from './password_reset_store.ts'
+export type { SessionManager } from './session_manager.ts'
+
+/** Re-export shared user port for convenience inside the auth module. */
+export type { AuthMethod, User, RegisterUserInput, UserStore } from '#modules/contracts/index'

package/registry/auth/contracts/password_reset_store.ts

@@ -0,0 +1,21 @@
+import type { User } from '#modules/contracts/index'
+import type { AuthPasswordReset, TokenDuration } from './types.ts'
+
+/**
+ * Host must implement this for password-reset flows.
+ */
+export interface PasswordResetStore {
+  /** Invalidate existing reset rows for the user, then create a new token. */
+  createForUser(userId: number, duration: TokenDuration): Promise<AuthPasswordReset>
+
+  findByToken(token: string): Promise<AuthPasswordReset | null>
+
+  deleteForUser(userId: number): Promise<void>
+
+  /** Rotate/replace the token with a new expiry window. */
+  refreshToken(reset: AuthPasswordReset, duration: TokenDuration): Promise<AuthPasswordReset>
+
+  findUserByReset(reset: AuthPasswordReset): Promise<User>
+}
+
+export type { AuthPasswordReset, TokenDuration }

package/registry/auth/contracts/session_manager.ts

@@ -0,0 +1,19 @@
+import type { User } from '#modules/contracts/index'
+
+/**
+ * Result of opening a session. Access-token hosts return token + expiry;
+ * cookie hosts may return {}.
+ */
+export type SessionResult = {
+  token?: string
+  expiresAt?: Date
+}
+
+/**
+ * Host HTTP/session (or access-token) bridge.
+ * Controllers pass an implementation; AuthService stays HTTP-free.
+ */
+export interface SessionManager {
+  login(user: User): Promise<SessionResult>
+  logout(): Promise<void>
+}

package/registry/auth/contracts/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Auth-only DTOs and input types.
+ * Shared User / UserStore live in #modules/contracts.
+ */
+import type { User } from '#modules/contracts/index'
+import type { SessionResult } from './session_manager.ts'
+
+export type AuthPasswordReset = {
+  id: number
+  userId: number
+  token: string
+  isExpired: boolean
+}
+
+export type LoginCredentials = {
+  email: string
+  password: string
+}
+
+export type UpdatePasswordInput = {
+  token: string
+  password: string
+}
+
+export type TokenDuration = { hours: number } | { minutes: number }
+
+export type { SessionResult }
+
+export type LoginResult = {
+  user: User
+  session: SessionResult
+}

package/registry/auth/events.ts

@@ -0,0 +1,21 @@
+/**
+ * Auth module events. Import this file so the EventsList augmentation loads.
+ */
+import type { User } from '#modules/contracts/index'
+
+type RequestPasswordReset = {
+  user: User
+  token: string
+}
+
+declare module '@adonisjs/core/types' {
+  interface EventsList {
+    'Auth:RegisterUser': User
+    'Auth:CreateNewVerificationToken': User
+    'Auth:ActivateUserAccount': User
+    'Auth:RequestPasswordReset': RequestPasswordReset
+    'Auth:ResetPassword': { user: User }
+    'Auth:Login': { user: User }
+    'Auth:Logout': null
+  }
+}

package/registry/auth/module.json

@@ -0,0 +1,45 @@
+{
+  "name": "auth",
+  "description": "Email registration, login, verification, password reset",
+  "files": [
+    "service.ts",
+    "events.ts",
+    "options.ts",
+    "contracts/**",
+    "module.json"
+  ],
+  "stubs": [
+    "stubs/models/user.ts",
+    "stubs/models/password_reset.ts",
+    "stubs/migrations/*.ts",
+    "stubs/controllers/auth_controller.ts",
+    "stubs/validators/**/*",
+    "stubs/providers/**/*",
+    "stubs/start/**/*",
+    "stubs/adapters/**/*",
+    "stubs/routes/auth.ts"
+  ],
+  "dependencies": {},
+  "registryDependencies": ["api"],
+  "peerModels": ["#models/user", "#models/password_reset"],
+  "configKeys": ["modules.auth"],
+  "env": ["APP_KEY"],
+  "events": [
+    "Auth:RegisterUser",
+    "Auth:CreateNewVerificationToken",
+    "Auth:ActivateUserAccount",
+    "Auth:RequestPasswordReset",
+    "Auth:ResetPassword",
+    "Auth:Login",
+    "Auth:Logout"
+  ],
+  "hostFacingExceptions": [
+    "INVALID_CREDENTIALS",
+    "UNAUTHENTICATED",
+    "SESSION_EXPIRED",
+    "FORBIDDEN",
+    "TOO_MANY_ATTEMPTS",
+    "TOO_MANY_REQUESTS"
+  ],
+  "hostTests": ["tests/integration/lucid_adapters.spec.ts"]
+}

package/registry/auth/options.ts

@@ -0,0 +1,23 @@
+import type { TokenDuration } from '#modules/auth/contracts/index'
+
+/**
+ * Host-editable defaults for AuthService.
+ * Do not read env here — pass values in when constructing the service.
+ */
+export type AuthOptions = {
+  /** Duration passed to encryption.encrypt for email verification tokens. */
+  verificationTtl: string
+  /** Lifetime of a newly requested password-reset token. */
+  passwordResetTtl: TokenDuration
+  /** Lifetime after validatePasswordResetToken rotates the token. */
+  passwordResetValidateTtl: TokenDuration
+  /** Byte length for string.generateRandom in LucidPasswordResetStore. */
+  passwordResetTokenBytes: number
+}
+
+export const defaultAuthOptions: AuthOptions = {
+  verificationTtl: '2 Hours',
+  passwordResetTtl: { hours: 2 },
+  passwordResetValidateTtl: { minutes: 5 },
+  passwordResetTokenBytes: 40,
+}