@stjoseph/prumo 0.0.1

package/templates/api/nest-cli.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true,
+    "tsConfigPath": "tsconfig.build.json",
+    "plugins": ["@nestjs/swagger/plugin"]
+  }
+}

package/templates/api/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "api",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "build": "nest build",
+    "start": "nest start",
+    "start:dev": "nest start --watch",
+    "start:prod": "node dist/main",
+    "lint": "biome check",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:cov": "vitest run --coverage",
+    "db:migrate": "nest build && auth migrate --config dist/auth/auth.js --yes && mikro-orm migration:up",
+    "db:migration:create": "mikro-orm migration:create",
+    "prepare": "node .githooks/install.mjs"
+  },
+  "dependencies": {
+    "@better-auth/expo": "1.7.4",
+    "@mikro-orm/core": "7.2.0",
+    "@mikro-orm/migrations": "7.2.0",
+    "@mikro-orm/nestjs": "7.1.0",
+    "@mikro-orm/postgresql": "7.2.0",
+    "@nestjs/common": "12.0.1",
+    "@nestjs/config": "12.0.0",
+    "@nestjs/core": "12.0.1",
+    "@nestjs/platform-express": "12.0.1",
+    "@nestjs/swagger": "12.0.1",
+    "@nestjs/terminus": "12.0.0",
+    "better-auth": "1.7.4",
+    "class-transformer": "0.5.1",
+    "class-validator": "0.15.1",
+    "nestjs-pino": "5.1.0",
+    "pg": "8.23.0",
+    "pino": "10.3.1",
+    "pino-http": "11.0.0",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.13",
+    "@mikro-orm/cli": "7.2.0",
+    "@nestjs/cli": "12.0.0",
+    "@nestjs/schematics": "12.0.1",
+    "@nestjs/testing": "12.0.1",
+    "@swc-node/register": "1.12.1",
+    "@swc/core": "1.16.2",
+    "@testcontainers/postgresql": "12.1.0",
+    "@types/express": "5.0.6",
+    "@types/node": "24.13.4",
+    "@types/pg": "8.23.1",
+    "@vitest/coverage-v8": "4.1.11",
+    "auth": "1.7.4",
+    "pino-pretty": "13.1.3",
+    "typescript": "6.0.3",
+    "unplugin-swc": "1.6.0",
+    "vitest": "4.1.11"
+  },
+  "engines": {
+    "node": ">=22.17.0"
+  },
+  "mikro-orm": {
+    "configPaths": [
+      "./src/mikro-orm.config.ts",
+      "./dist/mikro-orm.config.js"
+    ]
+  }
+}

package/templates/api/pnpm-workspace.yaml

@@ -0,0 +1,9 @@
+allowBuilds:
+  # Its install script only sends usage telemetry; it arrives through @nestjs/swagger's swagger-ui-dist.
+  '@scarf/scarf': false
+  # Its platform binary arrives as an optional dependency, so the install script is not needed.
+  '@swc/core': false
+  # These three arrive through Testcontainers, and the suite runs without their native builds.
+  cpu-features: false
+  protobufjs: false
+  ssh2: false

package/templates/api/src/app.module.ts

@@ -0,0 +1,46 @@
+import { MikroOrmModule } from '@mikro-orm/nestjs'
+import { PostgreSqlDriver } from '@mikro-orm/postgresql'
+import { type MiddlewareConsumer, Module, type NestModule } from '@nestjs/common'
+import { APP_FILTER } from '@nestjs/core'
+import { LoggerModule } from 'nestjs-pino'
+import { AuthModule } from '@/auth/auth.module'
+import { Env } from '@/config/env'
+import { EnvModule } from '@/config/env.module'
+import { ProblemDetailsFilter } from '@/errors/problem-details.filter'
+import { HealthModule } from '@/health/health.module'
+import { createOrmConfig } from '@/mikro-orm.factory'
+import { RequestContextModule } from '@/request-context/request-context.module'
+import { RequestIdMiddleware } from '@/request-context/request-id.middleware'
+import { UsersModule } from '@/users/users.module'
+
+@Module({
+  imports: [
+    EnvModule,
+    LoggerModule.forRootAsync({
+      inject: [Env],
+      useFactory: (env: Env) => ({
+        pinoHttp: {
+          level: env.LOG_LEVEL,
+          redact: ['req.headers.authorization', 'req.headers.cookie', 'res.headers["set-cookie"]'],
+          transport: env.NODE_ENV === 'development' ? { target: 'pino-pretty' } : undefined,
+          autoLogging: { ignore: (req) => req.url?.startsWith('/api/health') === true },
+        },
+      }),
+    }),
+    MikroOrmModule.forRootAsync({
+      inject: [Env],
+      driver: PostgreSqlDriver,
+      useFactory: (env: Env) => createOrmConfig(env),
+    }),
+    RequestContextModule,
+    AuthModule,
+    HealthModule,
+    UsersModule,
+  ],
+  providers: [{ provide: APP_FILTER, useClass: ProblemDetailsFilter }],
+})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer): void {
+    consumer.apply(RequestIdMiddleware).forRoutes('*path')
+  }
+}

package/templates/api/src/auth/auth.constants.ts

@@ -0,0 +1,2 @@
+export const AUTH = Symbol('AUTH')
+export const IS_PUBLIC = Symbol('IS_PUBLIC')

package/templates/api/src/auth/auth.controller.ts

@@ -0,0 +1,19 @@
+import { All, Controller, Inject, Req, Res, VERSION_NEUTRAL } from '@nestjs/common'
+import { ApiExcludeController } from '@nestjs/swagger'
+import { toNodeHandler } from 'better-auth/node'
+import type { Request, Response } from 'express'
+import { AUTH } from './auth.constants'
+import type { Auth } from './auth.factory'
+import { Public } from './public.decorator'
+
+@ApiExcludeController()
+@Controller({ path: 'auth', version: VERSION_NEUTRAL })
+export class AuthController {
+  constructor(@Inject(AUTH) private readonly auth: Auth) {}
+
+  @Public()
+  @All('*path')
+  handle(@Req() request: Request, @Res() response: Response): Promise<void> {
+    return toNodeHandler(this.auth)(request, response)
+  }
+}

package/templates/api/src/auth/auth.factory.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest'
+import { testDatabaseUrl } from '../../test/setup'
+import { createAuth } from './auth.factory'
+
+const env = () => ({
+  AUTH_DATABASE_URL: testDatabaseUrl(),
+  BETTER_AUTH_SECRET: 'test-secret-that-is-at-least-32-characters',
+  BETTER_AUTH_URL: 'http://localhost:3000',
+  WEB_ORIGIN: 'http://localhost:5173',
+})
+
+const proxy =
+  'http://localhost:3000/api/auth/expo-authorization-proxy?authorizationURL=https://example.com/authorize&oauthState=s'
+
+describe('createAuth', () => {
+  it('exposes no Expo redirect endpoint without a mobile scheme', async () => {
+    const response = await createAuth(env()).handler(new Request(proxy))
+
+    expect(response.status).toBe(404)
+  })
+
+  it('exposes the Expo endpoint and trusts the scheme once a mobile scheme is set', async () => {
+    const auth = createAuth({ ...env(), MOBILE_APP_SCHEME: 'app' })
+    const response = await auth.handler(new Request(proxy))
+
+    expect(response.status).toBe(302)
+    expect(auth.options.trustedOrigins).toContain('app://')
+  })
+})

package/templates/api/src/auth/auth.factory.ts

@@ -0,0 +1,52 @@
+import { expo } from '@better-auth/expo'
+import { type BetterAuthPlugin, betterAuth } from 'better-auth'
+import { Pool } from 'pg'
+import type { Env } from '@/config/env'
+
+type NewUser = { id: string; name: string }
+
+export type AuthHooks = {
+  onUserCreated?: (user: NewUser) => Promise<void>
+}
+
+export function createAuth(
+  env: Pick<
+    Env,
+    | 'AUTH_DATABASE_URL'
+    | 'BETTER_AUTH_SECRET'
+    | 'BETTER_AUTH_URL'
+    | 'WEB_ORIGIN'
+    | 'MOBILE_APP_SCHEME'
+  >,
+  hooks: AuthHooks = {},
+) {
+  const mobile = env.MOBILE_APP_SCHEME
+  const plugins: BetterAuthPlugin[] = mobile === undefined ? [] : [expo()]
+
+  return betterAuth({
+    baseURL: env.BETTER_AUTH_URL,
+    basePath: '/api/auth',
+    secret: env.BETTER_AUTH_SECRET,
+    trustedOrigins: mobile === undefined ? [env.WEB_ORIGIN] : [env.WEB_ORIGIN, `${mobile}://`],
+    plugins,
+    database: new Pool({
+      connectionString: env.AUTH_DATABASE_URL,
+      options: '-c search_path=auth',
+    }),
+    emailAndPassword: { enabled: true },
+    advanced: { database: { generateId: 'uuid' } },
+    databaseHooks: {
+      user: {
+        create: {
+          after: async (user) => {
+            await hooks.onUserCreated?.(user)
+          },
+        },
+      },
+    },
+  })
+}
+
+export type Auth = ReturnType<typeof createAuth>
+export type AuthSession = Awaited<ReturnType<Auth['api']['getSession']>>
+export type AuthUser = NonNullable<AuthSession>['user']

package/templates/api/src/auth/auth.guard.ts

@@ -0,0 +1,43 @@
+import {
+  type CanActivate,
+  type ExecutionContext,
+  Inject,
+  Injectable,
+  UnauthorizedException,
+} from '@nestjs/common'
+import { Reflector } from '@nestjs/core'
+import { fromNodeHeaders } from 'better-auth/node'
+import type { Request } from 'express'
+import { AUTH, IS_PUBLIC } from './auth.constants'
+import type { Auth } from './auth.factory'
+
+@Injectable()
+export class AuthGuard implements CanActivate {
+  constructor(
+    private readonly reflector: Reflector,
+    @Inject(AUTH) private readonly auth: Auth,
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context.switchToHttp().getRequest<Request>()
+    const session = await this.auth.api.getSession({ headers: fromNodeHeaders(request.headers) })
+
+    request.user = session?.user
+    request.session = session?.session
+
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC, [
+      context.getHandler(),
+      context.getClass(),
+    ])
+
+    if (isPublic === true) {
+      return true
+    }
+
+    if (session === null) {
+      throw new UnauthorizedException()
+    }
+
+    return true
+  }
+}

package/templates/api/src/auth/auth.module.ts

@@ -0,0 +1,30 @@
+import { Global, Module } from '@nestjs/common'
+import { APP_GUARD } from '@nestjs/core'
+import { Env } from '@/config/env'
+import { UsersModule } from '@/users/users.module'
+import { UsersService } from '@/users/users.service'
+import { AUTH } from './auth.constants'
+import { AuthController } from './auth.controller'
+import { createAuth } from './auth.factory'
+import { AuthGuard } from './auth.guard'
+
+@Global()
+@Module({
+  imports: [UsersModule],
+  controllers: [AuthController],
+  providers: [
+    {
+      provide: AUTH,
+      inject: [Env, UsersService],
+      useFactory: (env: Env, users: UsersService) =>
+        createAuth(env, {
+          onUserCreated: async (user) => {
+            await users.createProfile(user.id, user.name)
+          },
+        }),
+    },
+    { provide: APP_GUARD, useClass: AuthGuard },
+  ],
+  exports: [AUTH],
+})
+export class AuthModule {}

package/templates/api/src/auth/auth.ts

@@ -0,0 +1,4 @@
+import { loadEnv } from '@/config/env'
+import { createAuth } from './auth.factory'
+
+export const auth = createAuth(loadEnv())

package/templates/api/src/auth/current-user.decorator.ts

@@ -0,0 +1,9 @@
+import { createParamDecorator, type ExecutionContext } from '@nestjs/common'
+import type { Request } from 'express'
+import type { AuthUser } from './auth.factory'
+
+export const CurrentUser = createParamDecorator(
+  (_data: unknown, context: ExecutionContext): AuthUser | undefined => {
+    return context.switchToHttp().getRequest<Request>().user
+  },
+)

package/templates/api/src/auth/express.d.ts

@@ -0,0 +1,10 @@
+import type { AuthSession, AuthUser } from './auth.factory'
+
+declare global {
+  namespace Express {
+    interface Request {
+      user?: AuthUser
+      session?: NonNullable<AuthSession>['session']
+    }
+  }
+}

package/templates/api/src/auth/public.decorator.ts

@@ -0,0 +1,4 @@
+import { SetMetadata } from '@nestjs/common'
+import { IS_PUBLIC } from './auth.constants'
+
+export const Public = () => SetMetadata(IS_PUBLIC, true)

package/templates/api/src/config/env.module.ts

@@ -0,0 +1,11 @@
+import { Global, Module } from '@nestjs/common'
+import { ConfigModule } from '@nestjs/config'
+import { Env, loadEnv } from './env'
+
+@Global()
+@Module({
+  imports: [ConfigModule.forRoot({ cache: true, ignoreEnvFile: true, validate: loadEnv })],
+  providers: [{ provide: Env, useFactory: loadEnv }],
+  exports: [Env],
+})
+export class EnvModule {}

package/templates/api/src/config/env.ts

@@ -0,0 +1,81 @@
+import 'reflect-metadata'
+import { existsSync } from 'node:fs'
+import { plainToInstance } from 'class-transformer'
+import {
+  IsEnum,
+  IsInt,
+  IsOptional,
+  IsString,
+  Matches,
+  Max,
+  Min,
+  MinLength,
+  validateSync,
+} from 'class-validator'
+
+export type NodeEnv = 'development' | 'test' | 'production'
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug'
+
+export class Env {
+  @IsEnum(['development', 'test', 'production'])
+  NODE_ENV: NodeEnv
+
+  @IsInt()
+  @Min(1)
+  @Max(65535)
+  PORT: number
+
+  @IsString()
+  @MinLength(1)
+  DATABASE_URL: string
+
+  @IsString()
+  @MinLength(1)
+  AUTH_DATABASE_URL: string
+
+  @IsString()
+  @MinLength(32)
+  BETTER_AUTH_SECRET: string
+
+  @IsString()
+  @MinLength(1)
+  BETTER_AUTH_URL: string
+
+  @IsString()
+  @MinLength(1)
+  WEB_ORIGIN: string
+
+  @IsOptional()
+  @Matches(/^[a-z][a-z0-9+.-]*$/)
+  MOBILE_APP_SCHEME?: string
+
+  @IsEnum(['error', 'warn', 'info', 'debug'])
+  LOG_LEVEL: LogLevel
+}
+
+export function validate(raw: Record<string, unknown>): Env {
+  const env = plainToInstance(Env, raw, { enableImplicitConversion: true })
+  const errors = validateSync(env, { whitelist: true, forbidUnknownValues: false })
+
+  if (errors.length > 0) {
+    const named = errors.map((error) => error.property).join(', ')
+    throw new Error(`Invalid environment: ${named}`)
+  }
+
+  loaded = env
+  return env
+}
+
+let loaded: Env | undefined
+
+export function loadEnv(): Env {
+  if (loaded !== undefined) {
+    return loaded
+  }
+
+  if (process.env.NODE_ENV !== 'production' && existsSync('.env')) {
+    process.loadEnvFile('.env')
+  }
+
+  return validate(process.env)
+}

package/templates/api/src/errors/problem-details.filter.ts

@@ -0,0 +1,86 @@
+import {
+  type ArgumentsHost,
+  Catch,
+  type ExceptionFilter,
+  HttpException,
+  HttpStatus,
+  Logger,
+} from '@nestjs/common'
+import type { Request, Response } from 'express'
+import { RequestContextService } from '@/request-context/request-context.service'
+import { ValidationFailedException } from './validation-exception.factory'
+
+type ProblemDocument = {
+  type: string
+  title: string
+  status: number
+  detail: string
+  instance: string
+  requestId?: string
+  errors?: Record<string, string[]>
+}
+
+const TITLES: Record<number, string> = {
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  403: 'Forbidden',
+  404: 'Not Found',
+  409: 'Conflict',
+  422: 'Unprocessable Entity',
+  500: 'Internal Server Error',
+  503: 'Service Unavailable',
+}
+
+function detailOf(exception: HttpException): string {
+  const response = exception.getResponse()
+
+  if (typeof response === 'string') {
+    return response
+  }
+
+  const message = (response as { message?: unknown }).message
+
+  if (typeof message === 'string') {
+    return message
+  }
+
+  return exception.message
+}
+
+@Catch()
+export class ProblemDetailsFilter implements ExceptionFilter {
+  private readonly logger = new Logger(ProblemDetailsFilter.name)
+
+  constructor(private readonly context: RequestContextService) {}
+
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const http = host.switchToHttp()
+    const request = http.getRequest<Request>()
+    const response = http.getResponse<Response>()
+
+    const status =
+      exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR
+
+    const problem: ProblemDocument = {
+      type: 'about:blank',
+      title: TITLES[status] ?? 'Error',
+      status,
+      detail:
+        exception instanceof HttpException && status < HttpStatus.INTERNAL_SERVER_ERROR
+          ? detailOf(exception)
+          : 'An unexpected error occurred.',
+      instance: request.originalUrl,
+      requestId: this.context.requestId,
+    }
+
+    if (exception instanceof ValidationFailedException) {
+      problem.errors = exception.fields
+    }
+
+    if (status >= HttpStatus.INTERNAL_SERVER_ERROR) {
+      this.logger.error(exception)
+    }
+
+    response.status(status).type('application/problem+json').json(problem)
+  }
+}

package/templates/api/src/errors/validation-exception.factory.ts

@@ -0,0 +1,30 @@
+import { BadRequestException, type ValidationError } from '@nestjs/common'
+
+export type FieldErrors = Record<string, string[]>
+
+function collect(errors: ValidationError[], prefix: string, into: FieldErrors): void {
+  for (const error of errors) {
+    const key = prefix === '' ? error.property : `${prefix}.${error.property}`
+    const messages = Object.values(error.constraints ?? {})
+
+    if (messages.length > 0) {
+      into[key] = messages
+    }
+
+    if (error.children !== undefined && error.children.length > 0) {
+      collect(error.children, key, into)
+    }
+  }
+}
+
+export class ValidationFailedException extends BadRequestException {
+  constructor(readonly fields: FieldErrors) {
+    super('Validation failed')
+  }
+}
+
+export function validationExceptionFactory(errors: ValidationError[]): ValidationFailedException {
+  const fields: FieldErrors = {}
+  collect(errors, '', fields)
+  return new ValidationFailedException(fields)
+}

package/templates/api/src/health/health.controller.ts

@@ -0,0 +1,32 @@
+import { Controller, Get, VERSION_NEUTRAL } from '@nestjs/common'
+import { ApiTags } from '@nestjs/swagger'
+import {
+  HealthCheck,
+  type HealthCheckResult,
+  HealthCheckService,
+  MikroOrmHealthIndicator,
+} from '@nestjs/terminus'
+import { Public } from '@/auth/public.decorator'
+
+@ApiTags('health')
+@Controller({ path: 'health', version: VERSION_NEUTRAL })
+export class HealthController {
+  constructor(
+    private readonly health: HealthCheckService,
+    private readonly database: MikroOrmHealthIndicator,
+  ) {}
+
+  @Public()
+  @Get('live')
+  @HealthCheck()
+  live(): Promise<HealthCheckResult> {
+    return this.health.check([])
+  }
+
+  @Public()
+  @Get('ready')
+  @HealthCheck()
+  ready(): Promise<HealthCheckResult> {
+    return this.health.check([() => this.database.pingCheck('database')])
+  }
+}

package/templates/api/src/health/health.module.ts

@@ -0,0 +1,9 @@
+import { Module } from '@nestjs/common'
+import { TerminusModule } from '@nestjs/terminus'
+import { HealthController } from './health.controller'
+
+@Module({
+  imports: [TerminusModule],
+  controllers: [HealthController],
+})
+export class HealthModule {}

package/templates/api/src/main.ts

@@ -0,0 +1,43 @@
+import { MikroORM } from '@mikro-orm/postgresql'
+import { ClassSerializerInterceptor, ValidationPipe, VersioningType } from '@nestjs/common'
+import { NestFactory, Reflector } from '@nestjs/core'
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'
+import { Logger } from 'nestjs-pino'
+import { AppModule } from './app.module'
+import { Env } from './config/env'
+import { validationExceptionFactory } from './errors/validation-exception.factory'
+
+async function bootstrap(): Promise<void> {
+  const app = await NestFactory.create(AppModule, { bufferLogs: true })
+  const env = app.get(Env)
+
+  app.useLogger(app.get(Logger))
+  app.setGlobalPrefix('api')
+  app.enableCors({ origin: env.WEB_ORIGIN, credentials: true, exposedHeaders: ['X-Request-Id'] })
+  app.enableVersioning({ type: VersioningType.URI })
+
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,
+      forbidNonWhitelisted: true,
+      transform: true,
+      exceptionFactory: validationExceptionFactory,
+    }),
+  )
+  app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)))
+
+  if (env.NODE_ENV !== 'production') {
+    const document = SwaggerModule.createDocument(
+      app,
+      new DocumentBuilder().setTitle('API').setVersion('1').build(),
+    )
+    SwaggerModule.setup('api/docs', app, document)
+  }
+
+  // MikroORM 7 no longer connects on init, so readiness would report the database down until a first query.
+  await app.get(MikroORM).connect()
+
+  await app.listen(env.PORT)
+}
+
+void bootstrap()

package/templates/api/src/mikro-orm.config.ts

@@ -0,0 +1,4 @@
+import { loadEnv } from './config/env'
+import { createOrmConfig } from './mikro-orm.factory'
+
+export default createOrmConfig(loadEnv())

package/templates/api/src/mikro-orm.factory.ts

@@ -0,0 +1,14 @@
+import { Migrator } from '@mikro-orm/migrations'
+import { defineConfig } from '@mikro-orm/postgresql'
+import type { Env } from './config/env'
+import { Profile } from './users/entities/profile.entity'
+
+export function createOrmConfig(env: Pick<Env, 'DATABASE_URL' | 'NODE_ENV'>) {
+  return defineConfig({
+    clientUrl: env.DATABASE_URL,
+    entities: [Profile],
+    extensions: [Migrator],
+    migrations: { path: './migrations', snapshot: false },
+    debug: env.NODE_ENV === 'development',
+  })
+}