adonia 0.1.0

package/registry/account/stubs/controllers/account_controller.ts

@@ -0,0 +1,190 @@
+/**
+ * Example account controller. Copy into app/controllers.
+ *
+ * Copy Vine provider (`providers/vine_provider.ts`) and register it in
+ * adonisrc.ts so unique/validPassword macros load (same provider as auth).
+ * Authenticated routes need named auth middleware from start/kernel.ts.
+ * Inbox methods need `#models/app_notification` from
+ * `adonia add notification --with-models`.
+ */
+import type { HttpContext } from '@adonisjs/core/http'
+import { DateTime } from 'luxon'
+import { createAccountService } from '#adapters/account'
+import { responseCodes } from '#constants/responseCodes'
+import User from '#models/user'
+import AppNotification from '#models/app_notification'
+import {
+  updateProfileValidator,
+  replaceEmailValidator,
+  replacePasswordValidator,
+  confirmEmailChangeValidator,
+  updateNotificationsValidator,
+} from '../validators/account.ts'
+
+const account = createAccountService()
+
+export default class AccountController {
+  async getAuthenticatedUser(ctx: HttpContext) {
+    const user = ctx.auth.getUserOrFail()
+    return ctx.response.ok(
+      await ctx.respond({
+        success: true,
+        message: responseCodes.USER_SHOW.code,
+        data: user,
+      })
+    )
+  }
+
+  async updateProfile(ctx: HttpContext) {
+    const user = ctx.auth.getUserOrFail()
+    const data = await ctx.request.validateUsing(updateProfileValidator)
+    const updated = await account.updateProfile(user.id, data)
+    return ctx.response.ok(
+      await ctx.respond({
+        success: true,
+        message: responseCodes.PROFILE_UPDATED.code,
+        data: updated,
+      })
+    )
+  }
+
+  async replaceEmail(ctx: HttpContext) {
+    const user = ctx.auth.getUserOrFail()
+    const data = await ctx.request.validateUsing(replaceEmailValidator)
+    const updated = await account.replaceEmail(user.id, data)
+    return ctx.response.ok(
+      await ctx.respond({
+        success: true,
+        message: responseCodes.EMAIL_VERIFICATION_SENT.code,
+        data: updated,
+      })
+    )
+  }
+
+  async confirmEmailChange(ctx: HttpContext) {
+    const { token } = await ctx.request.validateUsing(confirmEmailChangeValidator)
+    const user = await account.confirmEmailChange(token)
+    return ctx.response.ok(
+      await ctx.respond({
+        success: true,
+        message: responseCodes.EMAIL_CHANGE_CONFIRMED.code,
+        data: user,
+      })
+    )
+  }
+
+  async replacePassword(ctx: HttpContext) {
+    const user = ctx.auth.getUserOrFail()
+    const data = await ctx.request.validateUsing(replacePasswordValidator)
+    await account.replacePassword(user.id, data)
+    return ctx.response.ok(
+      await ctx.respond({
+        success: true,
+        message: responseCodes.PASSWORD_UPDATED.code,
+        data: null,
+      })
+    )
+  }
+
+  async deleteAccount(ctx: HttpContext) {
+    const user = ctx.auth.getUserOrFail()
+    await account.deleteAccount(user.id)
+    return ctx.response.ok(
+      await ctx.respond({
+        success: true,
+        message: responseCodes.ACCOUNT_DELETED.code,
+        data: null,
+      })
+    )
+  }
+
+  async getNotifications(ctx: HttpContext) {
+    const authUser = ctx.auth.getUserOrFail()
+    const user = await User.findOrFail(authUser.id)
+    return ctx.response.ok(
+      await ctx.respond({
+        success: true,
+        message: responseCodes.NOTIFICATIONS_FETCHED.code,
+        data: {
+          emailMarketing: user.emailMarketing,
+          emailProductUpdates: user.emailProductUpdates,
+          emailSecurityAlerts: user.emailSecurityAlerts,
+          emailWeeklyDigest: user.emailWeeklyDigest,
+        },
+      })
+    )
+  }
+
+  async updateNotifications(ctx: HttpContext) {
+    const authUser = ctx.auth.getUserOrFail()
+    const data = await ctx.request.validateUsing(updateNotificationsValidator)
+    const user = await User.findOrFail(authUser.id)
+    if (data.emailMarketing !== undefined) user.emailMarketing = data.emailMarketing
+    if (data.emailProductUpdates !== undefined) {
+      user.emailProductUpdates = data.emailProductUpdates
+    }
+    if (data.emailSecurityAlerts !== undefined) {
+      user.emailSecurityAlerts = data.emailSecurityAlerts
+    }
+    if (data.emailWeeklyDigest !== undefined) user.emailWeeklyDigest = data.emailWeeklyDigest
+    await user.save()
+    return ctx.response.ok(
+      await ctx.respond({
+        success: true,
+        message: responseCodes.NOTIFICATIONS_UPDATED.code,
+        data: {
+          emailMarketing: user.emailMarketing,
+          emailProductUpdates: user.emailProductUpdates,
+          emailSecurityAlerts: user.emailSecurityAlerts,
+          emailWeeklyDigest: user.emailWeeklyDigest,
+        },
+      })
+    )
+  }
+
+  async getInboxNotifications(ctx: HttpContext) {
+    const user = ctx.auth.getUserOrFail()
+    const rows = await AppNotification.query()
+      .where('userId', user.id)
+      .orderBy('createdAt', 'desc')
+    return ctx.response.ok(
+      await ctx.respond({
+        success: true,
+        message: responseCodes.INBOX_FETCHED.code,
+        data: rows,
+      })
+    )
+  }
+
+  async markAllNotificationsRead(ctx: HttpContext) {
+    const user = ctx.auth.getUserOrFail()
+    await AppNotification.query()
+      .where('userId', user.id)
+      .whereNull('readAt')
+      .update({ readAt: DateTime.now().toSQL() })
+    return ctx.response.ok(
+      await ctx.respond({
+        success: true,
+        message: responseCodes.INBOX_MARKED_ALL_READ.code,
+        data: null,
+      })
+    )
+  }
+
+  async markNotificationRead(ctx: HttpContext) {
+    const user = ctx.auth.getUserOrFail()
+    const notification = await AppNotification.query()
+      .where('id', ctx.params.id)
+      .where('userId', user.id)
+      .firstOrFail()
+    notification.readAt = DateTime.now()
+    await notification.save()
+    return ctx.response.ok(
+      await ctx.respond({
+        success: true,
+        message: responseCodes.INBOX_MARKED_READ.code,
+        data: notification,
+      })
+    )
+  }
+}

package/registry/account/stubs/routes/account.ts

@@ -0,0 +1,53 @@
+/**
+ * Example account routes. Requires controllers (and typically validators)
+ * installed via `adonia add account --with-controllers --with-validators`
+ * or `--with-stubs`.
+ *
+ * Copy Vine provider (`providers/vine_provider.ts`) and register it in
+ * adonisrc.ts. Authenticated routes need named auth middleware from
+ * start/kernel.ts. POST email/confirm is public (token in the body).
+ * Inbox routes need `adonia add notification --with-models`.
+ *
+ * Account routes should use accountLimiter (60/min). Install
+ * @adonisjs/limiter, copy stubs/start/limiter.ts, then uncomment
+ * `.use(accountLimiter)` below.
+ */
+import router from '@adonisjs/core/services/router'
+// import { middleware } from '#start/kernel'
+// import { accountLimiter } from '#start/limiter'
+
+const AccountController = () => import('#controllers/account_controller')
+
+router
+  .group(() => {
+    router.get('user', [AccountController, 'getAuthenticatedUser'])
+    // .use(middleware.auth())
+  })
+  .prefix('/api/v1')
+  .as('adonia.user')
+
+router
+  .group(() => {
+    router.patch('profile', [AccountController, 'updateProfile'])
+    // .use(middleware.auth())
+    router.post('email', [AccountController, 'replaceEmail'])
+    // .use(middleware.auth())
+    router.post('email/confirm', [AccountController, 'confirmEmailChange'])
+    router.post('password', [AccountController, 'replacePassword'])
+    // .use(middleware.auth())
+    router.get('notifications', [AccountController, 'getNotifications'])
+    // .use(middleware.auth())
+    router.put('notifications', [AccountController, 'updateNotifications'])
+    // .use(middleware.auth())
+    router.delete('/', [AccountController, 'deleteAccount'])
+    // .use(middleware.auth())
+    router.get('inbox', [AccountController, 'getInboxNotifications'])
+    // .use(middleware.auth())
+    router.post('inbox/read-all', [AccountController, 'markAllNotificationsRead'])
+    // .use(middleware.auth())
+    router.patch('inbox/:id', [AccountController, 'markNotificationRead'])
+    // .use(middleware.auth())
+  })
+  .prefix('/api/v1/account')
+  .as('adonia.account')
+  // .use(accountLimiter)

package/registry/account/stubs/validators/account.ts

@@ -0,0 +1,37 @@
+import vine from '@vinejs/vine'
+
+export const updateProfileValidator = vine.compile(
+  vine.object({
+    firstName: vine.string().trim().maxLength(80).optional(),
+    lastName: vine.string().trim().maxLength(80).optional(),
+    avatarKey: vine.string().nullable().optional(),
+  })
+)
+
+export const replaceEmailValidator = vine.compile(
+  vine.object({
+    email: vine.string().email().normalizeEmail().unique({ table: 'users', column: 'email' }),
+  })
+)
+
+export const confirmEmailChangeValidator = vine.compile(
+  vine.object({
+    token: vine.string(),
+  })
+)
+
+export const replacePasswordValidator = vine.compile(
+  vine.object({
+    currentPassword: vine.string(),
+    newPassword: vine.string().validPassword().confirmed(),
+  })
+)
+
+export const updateNotificationsValidator = vine.compile(
+  vine.object({
+    emailMarketing: vine.boolean().optional(),
+    emailProductUpdates: vine.boolean().optional(),
+    emailSecurityAlerts: vine.boolean().optional(),
+    emailWeeklyDigest: vine.boolean().optional(),
+  })
+)

package/registry/account/tests/account_service.spec.ts

@@ -0,0 +1,132 @@
+import { test } from '@japa/runner'
+import assert from 'node:assert/strict'
+import encryption from '@adonisjs/core/services/encryption'
+import { defaultAccountOptions } from '#modules/account/options'
+import { AccountService } from '#modules/account/service'
+import { AuthService } from '#modules/auth/service'
+import { MemoryUserStore } from '#modules/auth/tests/fakes/memory_user_store'
+import { MemoryPasswordResetStore } from '#modules/auth/tests/fakes/memory_password_reset_store'
+import { MemorySessionManager } from '#modules/auth/tests/fakes/memory_session_manager'
+import { MemoryAvatarStorage } from '#modules/account/tests/fakes/memory_avatar_storage'
+
+function makeAccount(users = new MemoryUserStore()) {
+  const avatars = new MemoryAvatarStorage()
+  const service = new AccountService(users, avatars)
+  const emissions: Array<{ event: string; payload: any }> = []
+  ;(service as any).emitSafe = async (event: string, payload: any) => {
+    emissions.push({ event, payload })
+  }
+  return { service, users, avatars, emissions }
+}
+
+test.group('AccountService - email change', () => {
+  test('after replaceEmail, login with the old address still succeeds', async () => {
+    const users = new MemoryUserStore()
+    const { service } = makeAccount(users)
+    const auth = new AuthService(users, new MemoryPasswordResetStore(users))
+    ;(auth as any).emitSafe = async () => {}
+
+    let user = await users.createEmailUser({ email: 'old@test.com', password: 'secret' })
+    user = await users.save({
+      ...user,
+      emailVerifiedAt: new Date(),
+      emailVerificationToken: null,
+    })
+
+    await service.replaceEmail(user.id, { email: 'new@test.com' })
+    const stored = await users.findOrFail(user.id)
+    assert.equal(stored.email, 'old@test.com')
+    assert.equal(stored.pendingEmail, 'new@test.com')
+
+    const session = new MemorySessionManager()
+    const result = await auth.loginByEmail(
+      { email: 'old@test.com', password: 'secret' },
+      session
+    )
+    assert.equal(result.user.email, 'old@test.com')
+  })
+
+  test('confirmEmailChange with mismatched token throws and leaves emails unchanged', async () => {
+    const { service, users } = makeAccount()
+    let user = await users.createEmailUser({ email: 'old@test.com', password: 'secret' })
+    user = await users.save({ ...user, emailVerifiedAt: new Date() })
+    await service.replaceEmail(user.id, { email: 'new@test.com' })
+
+    await assert.rejects(
+      () =>
+        service.confirmEmailChange(
+          encryption.encrypt('wrong@test.com', defaultAccountOptions.emailChangeTtl)
+        ),
+      (err: any) => {
+        assert.equal(err.code, 'E_INVALID_TOKEN')
+        return true
+      }
+    )
+
+    const stored = await users.findOrFail(user.id)
+    assert.equal(stored.email, 'old@test.com')
+    assert.equal(stored.pendingEmail, 'new@test.com')
+  })
+
+  test('confirmEmailChange rejects if another user owns pendingEmail', async () => {
+    const { service, users } = makeAccount()
+
+    let user = await users.createEmailUser({ email: 'old@test.com', password: 'secret' })
+    user = await users.save({ ...user, emailVerifiedAt: new Date() })
+    const updated = await service.replaceEmail(user.id, { email: 'soon-taken@test.com' })
+
+    // Race: address claimed after the change was requested
+    await users.createEmailUser({ email: 'soon-taken@test.com', password: 'x' })
+
+    await assert.rejects(
+      () => service.confirmEmailChange(updated.emailVerificationToken!),
+      (err: any) => {
+        assert.equal(err.code, 'E_EMAIL_EXISTS')
+        return true
+      }
+    )
+  })
+
+  test('confirmEmailChange swaps pendingEmail into email', async () => {
+    const { service, users, emissions } = makeAccount()
+    let user = await users.createEmailUser({ email: 'old@test.com', password: 'secret' })
+    user = await users.save({ ...user, emailVerifiedAt: new Date() })
+    const pending = await service.replaceEmail(user.id, { email: 'new@test.com' })
+    const confirmed = await service.confirmEmailChange(pending.emailVerificationToken!)
+
+    assert.equal(confirmed.email, 'new@test.com')
+    assert.equal(confirmed.pendingEmail, null)
+    assert.ok(confirmed.emailVerifiedAt)
+    assert.ok(emissions.some((e) => e.event === 'Account:ConfirmEmailChange'))
+  })
+})
+
+test.group('AccountService - password and delete', () => {
+  test('replacePassword with wrong current password throws E_INVALID_PASSWORD', async () => {
+    const { service, users } = makeAccount()
+    const user = await users.createEmailUser({ email: 'a@test.com', password: 'secret' })
+
+    await assert.rejects(
+      () =>
+        service.replacePassword(user.id, {
+          currentPassword: 'wrong',
+          newPassword: 'new-secret',
+        }),
+      (err: any) => {
+        assert.equal(err.code, 'E_INVALID_PASSWORD')
+        return true
+      }
+    )
+  })
+
+  test('deleteAccount removes the avatar and the user', async () => {
+    const { service, users, avatars } = makeAccount()
+    let user = await users.createEmailUser({ email: 'a@test.com', password: 'secret' })
+    user = await users.save({ ...user, avatarKey: 'avatars/1.png' })
+
+    await service.deleteAccount(user.id)
+
+    assert.deepEqual(avatars.deleted, ['avatars/1.png'])
+    assert.equal(users.users.has(user.id), false)
+  })
+})

package/registry/account/tests/fakes/memory_avatar_storage.ts

@@ -0,0 +1,12 @@
+import type { AvatarStorage } from '#modules/account/contracts/index'
+
+/**
+ * In-memory AvatarStorage that records deleted keys.
+ */
+export class MemoryAvatarStorage implements AvatarStorage {
+  deleted: string[] = []
+
+  async delete(key: string): Promise<void> {
+    this.deleted.push(key)
+  }
+}

package/registry/api/envelope.ts

@@ -0,0 +1,66 @@
+/**
+ * Runtime helpers for the shared API envelope.
+ * Types live in modules/types/api.ts.
+ */
+import type {
+  ApiErrorBody,
+  ApiResponse,
+  ApiResult,
+  PaginatedResponse,
+} from '#modules/types/api'
+
+/**
+ * Build the shared failure envelope used by ApiService and the exception handler.
+ */
+export function prepareError(message: string, status?: number): ApiErrorBody {
+  return {
+    success: false,
+    message,
+    ...(status !== undefined && { status }),
+  }
+}
+
+export function isApiError(
+  result: unknown
+): result is Extract<ApiResult<never>, { success: false }> {
+  return (
+    typeof result === 'object' &&
+    result !== null &&
+    'success' in result &&
+    (result as { success: unknown }).success === false &&
+    'message' in result
+  )
+}
+
+/**
+ * Paginated envelopes carry `meta`. Checked before isApiResponse so a
+ * PaginatedResponse is not treated as a plain ApiResponse.
+ */
+export function isPaginatedResponse(result: unknown): result is PaginatedResponse<unknown> {
+  return (
+    typeof result === 'object' &&
+    result !== null &&
+    'success' in result &&
+    (result as { success: unknown }).success === true &&
+    'data' in result &&
+    'message' in result &&
+    'meta' in result &&
+    typeof (result as { meta: unknown }).meta === 'object' &&
+    (result as { meta: unknown }).meta !== null &&
+    'total' in (result as { meta: object }).meta &&
+    'page' in (result as { meta: object }).meta &&
+    'pageSize' in (result as { meta: object }).meta &&
+    'totalPages' in (result as { meta: object }).meta
+  )
+}
+
+export function isApiResponse(result: unknown): result is ApiResponse<unknown> {
+  return (
+    typeof result === 'object' &&
+    result !== null &&
+    'success' in result &&
+    (result as { success: unknown }).success === true &&
+    'data' in result &&
+    'message' in result
+  )
+}

package/registry/api/exception.ts

@@ -0,0 +1,38 @@
+import { Exception } from '@adonisjs/core/exceptions'
+import type { StatusCodeEntry } from '#modules/types/constants'
+
+type ApiExceptionOptions = {
+  status?: number
+  code?: string
+  message?: string
+  cause?: unknown
+}
+
+/**
+ * Domain exception carrier. No custom handle() — the API exception handler
+ * formats every error (framework + ApiException) through one JSON envelope.
+ *
+ * @example
+ * throw new ApiException('E_INVALID_TOKEN', { status: 400 })
+ * throw ApiException.from(exceptions.INVALID_TOKEN)
+ */
+export default class ApiException extends Exception {
+  constructor(code: string, options: ApiExceptionOptions = {}) {
+    super(options.message ?? code, {
+      status: options.status ?? 400,
+      code,
+      cause: options.cause,
+    })
+  }
+
+  /**
+   * Build from a modules/constants exceptions entry.
+   */
+  static from(entry: StatusCodeEntry, cause?: unknown) {
+    return new ApiException(entry.code, {
+      status: entry.status,
+      code: entry.code,
+      cause,
+    })
+  }
+}

package/registry/api/exception_handler.ts

@@ -0,0 +1,54 @@
+import { type HttpContext, ExceptionHandler } from '@adonisjs/core/http'
+import { prepareError } from '#modules/api/envelope'
+
+type HttpError = Parameters<ExceptionHandler['renderErrorAsJSON']>[0]
+
+/**
+ * Global API exception handler.
+ *
+ * Overrides JSON renderers so Adonis package errors, validation errors, and
+ * AppException all share one envelope — no per-package instanceof branches.
+ */
+export default class HttpExceptionHandler extends ExceptionHandler {
+  /**
+   * Youch debug payloads are unused for this API (force_json middleware).
+   * Always emit the envelope so clients get a stable shape in every environment.
+   */
+  protected debug = false
+
+  /**
+   * Client errors are expected; skip noisy logs for common statuses.
+   */
+  protected ignoreStatuses = [400, 401, 403, 404, 422]
+
+  async handle(error: unknown, ctx: HttpContext) {
+    return super.handle(error, ctx)
+  }
+
+  async report(error: unknown, ctx: HttpContext) {
+    return super.report(error, ctx)
+  }
+
+  /**
+   * All non-validation errors that accept JSON land here
+   * (auth, limiter, route not found, AppException, unknown, …).
+   */
+  async renderErrorAsJSON(error: HttpError, ctx: HttpContext): Promise<void> {
+    const message = error.code ?? error.message
+    ctx.response.status(error.status).json(prepareError(message, error.status))
+  }
+
+  /**
+   * Vine validation is the one structured special case (field messages[]).
+   */
+  async renderValidationErrorAsJSON(error: HttpError, ctx: HttpContext): Promise<void> {
+    const messages = error.messages as Array<{ message?: string }> | undefined
+    const firstMessage = messages?.[0]?.message
+    const message = firstMessage ?? error.code ?? error.message
+
+    ctx.response.status(error.status).json({
+      ...prepareError(message, error.status),
+      errors: error.messages,
+    })
+  }
+}

package/registry/api/module.json

@@ -0,0 +1,27 @@
+{
+  "name": "api",
+  "description": "Shared ApiService, envelopes, exception handler, and HttpContext.respond provider",
+  "files": [
+    "service.ts",
+    "envelope.ts",
+    "exception.ts",
+    "exception_handler.ts",
+    "provider.ts",
+    "module.json"
+  ],
+  "stubs": [],
+  "dependencies": {},
+  "registryDependencies": [
+    "types",
+    "constants",
+    "contracts"
+  ],
+  "peerModels": [],
+  "configKeys": [],
+  "env": [],
+  "events": [],
+  "hostFacingExceptions": [],
+  "hostTests": [
+    "tests/integration/"
+  ]
+}