@aurostack/stacks 0.1.0

package/templates/nest-api/files/src/common/entity/pagination.entity.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+
+/** What `db.x.<model>.paginate()` returns alongside the page of rows. */
+export interface PaginationMeta {
+	total: number;
+	pageSize: number;
+	currentPage: number;
+	lastPage: number;
+}
+
+/**
+ * A page of `item`, published in OpenAPI as the component `id`
+ * (e.g. `PaginatedUserEntity`).
+ */
+export const paginated = <T extends z.ZodType>(item: T, id: string) =>
+	z
+		.object({
+			total: z.number(),
+			pageSize: z.number(),
+			currentPage: z.number(),
+			lastPage: z.number(),
+			list: z.array(item)
+		})
+		.meta({ id });

package/templates/nest-api/files/src/common/exceptions/index.ts

@@ -0,0 +1 @@
+export * from './prisma.exception';

package/templates/nest-api/files/src/common/exceptions/prisma.exception.ts

@@ -0,0 +1,57 @@
+import {
+	ArgumentsHost,
+	Catch,
+	HttpStatus,
+	BadRequestException
+} from '@nestjs/common';
+import { BaseExceptionFilter } from '@nestjs/core';
+import { Response } from 'express';
+import { Prisma } from '@db/client';
+
+@Catch(Prisma.PrismaClientKnownRequestError)
+export class PrismaClientKnownRequestExceptionFilter extends BaseExceptionFilter {
+	catch(exception: Prisma.PrismaClientKnownRequestError, host: ArgumentsHost) {
+		const ctx = host.switchToHttp();
+		const response = ctx.getResponse<Response>();
+
+		switch (exception.code) {
+			case 'P2002':
+				response.status(HttpStatus.CONFLICT).json({
+					statusCode: HttpStatus.CONFLICT,
+					message: 'A record already exists with the same unique fields'
+				});
+				break;
+			case 'P2001':
+			case 'P2015':
+			case 'P2016':
+			case 'P2025':
+				response.status(HttpStatus.NOT_FOUND).json({
+					statusCode: HttpStatus.NOT_FOUND,
+					message: exception.message.replace(/\n/g, '')
+				});
+				break;
+			default:
+				// console.log({ exception, host });
+				// default 500 error code
+				super.catch(exception, host);
+				break;
+		}
+	}
+}
+
+@Catch(Prisma.PrismaClientValidationError)
+export class PrismaClientValidationExceptionFilter extends BaseExceptionFilter {
+	catch(exception: Prisma.PrismaClientValidationError, host: ArgumentsHost) {
+		const ctx = host.switchToHttp();
+		const response = ctx.getResponse<Response>();
+
+		// console.log({ exception, host });
+
+		const badRequestException = new BadRequestException('Validation error');
+
+		response.status(badRequestException.getStatus()).json({
+			statusCode: badRequestException.getStatus(),
+			message: badRequestException.message
+		});
+	}
+}

package/templates/nest-api/files/src/common/guards/feature-flag.guard.ts

@@ -0,0 +1,51 @@
+import {
+	CanActivate,
+	ExecutionContext,
+	ForbiddenException,
+	Injectable,
+	SetMetadata,
+	UseGuards,
+	applyDecorators
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { FeatureFlagService, type AppFeatures } from 'common/services';
+
+export const FEATURE_FLAG_KEY = 'feature-flag';
+
+@Injectable()
+export class FeatureFlagGuard implements CanActivate {
+	constructor(
+		private readonly reflector: Reflector,
+		private readonly flags: FeatureFlagService
+	) {}
+
+	async canActivate(context: ExecutionContext): Promise<boolean> {
+		const flag = this.reflector.getAllAndOverride<
+			(string & keyof AppFeatures) | undefined
+		>(FEATURE_FLAG_KEY, [context.getHandler(), context.getClass()]);
+
+		if (!flag) return true;
+
+		// Evaluate with the session user's attributes so GrowthBook targeting
+		// (e.g. a `role`-scoped rule, or a percentage rollout by `id`) applies.
+		// Anonymous routes (no session) fall back to a plain global evaluation.
+		const user = context.switchToHttp().getRequest()?.session?.user;
+		const attributes = user ? { id: user.id, role: user.role } : {};
+
+		if (this.flags.isOn(flag, attributes)) return true;
+
+		throw new ForbiddenException('This feature is not currently available.');
+	}
+}
+
+/**
+ * Gate a route (or controller) behind a GrowthBook boolean flag. Responds 403
+ * when the flag is off or cannot be resolved. Signed-in requests are evaluated
+ * with the user's `id` and `role`; anonymous ones globally.
+ */
+export function RequireFeature(flag: string & keyof AppFeatures) {
+	return applyDecorators(
+		SetMetadata(FEATURE_FLAG_KEY, flag),
+		UseGuards(FeatureFlagGuard)
+	);
+}

package/templates/nest-api/files/src/common/guards/index.ts

@@ -0,0 +1 @@
+export * from './feature-flag.guard'; // @feature feature-flags

package/templates/nest-api/files/src/common/interceptors/index.ts

@@ -0,0 +1 @@
+export * from './metrics.interceptor'; // @feature observability

package/templates/nest-api/files/src/common/interceptors/metrics.interceptor.ts

@@ -0,0 +1,37 @@
+import {
+	Injectable,
+	NestInterceptor,
+	ExecutionContext,
+	CallHandler
+} from '@nestjs/common';
+import { InjectMetric } from '@willsoto/nestjs-prometheus';
+import { Histogram } from 'prom-client';
+import { Observable, tap } from 'rxjs';
+
+@Injectable()
+export class MetricsInterceptor implements NestInterceptor {
+	constructor(
+		@InjectMetric('http_request_duration_seconds')
+		private readonly histogram: Histogram<string>
+	) {}
+
+	intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+		if (context.getType() !== 'http') {
+			return next.handle();
+		}
+
+		const http = context.switchToHttp();
+		const req = http.getRequest();
+		const res = http.getResponse();
+		const stop = this.histogram.startTimer();
+
+		const observe = () =>
+			stop({
+				method: req.method,
+				route: req.route?.path ?? 'unmatched',
+				status: res.statusCode
+			});
+
+		return next.handle().pipe(tap({ next: observe, error: observe }));
+	}
+}

package/templates/nest-api/files/src/common/misc/helpers.ts

@@ -0,0 +1,26 @@
+import { Prisma } from '@db/client';
+
+/**
+ * Takes a number or string as input and creates a
+ * new Prisma Decimal instance with that value.
+ * This function is useful for working with decimal
+ * values in a Prisma context.
+ */
+export const dcml = (n: number | string) => new Prisma.Decimal(n);
+
+/**
+ * Builds an array of allowed origins for CORS based on the provided hostname.
+ * It includes the main domain and subdomains for app, auth, and admin.
+ *
+ * @param hostname - The base hostname to build origins from.
+ * @returns An array of allowed origins for CORS.
+ */
+export const buildOrigins = (hostname: string) => {
+	const protocol = 'https://';
+	const subdomains = ['auth', 'app', 'admin'];
+	const mainDomain = protocol + hostname;
+	return [
+		mainDomain,
+		...subdomains.map((subdomain) => `${protocol}${subdomain}.${hostname}`)
+	];
+};

package/templates/nest-api/files/src/common/misc/index.ts

@@ -0,0 +1,3 @@
+export * from './helpers';
+export * from './origin-builder';
+export * from './prisma.indicator'; // @feature observability

package/templates/nest-api/files/src/common/misc/origin-builder.ts

@@ -0,0 +1,56 @@
+/**
+ * Builds a list of origins for CORS configuration, given a list of hostnames.
+ * Each hostname will generate the main domain and subdomains
+ * for app, auth, and admin.
+ *
+ * @remarks This is mainly for development purposes
+ * For frontend developers on the team who cannot run a standalone
+ * backend server, they can use a central backend dev server with
+ * their individual frontend subdomains.
+ */
+export class OriginBuilder {
+	private static instance: OriginBuilder;
+
+	private readonly protocol = 'https://';
+	private readonly subdomains = ['auth', 'app', 'admin'];
+
+	private constructor() {}
+
+	static getInstance(): OriginBuilder {
+		return (this.instance ??= new OriginBuilder());
+	}
+
+	static build(hostnames?: string | string[]): string[] {
+		return OriginBuilder.getInstance().fromHosts(hostnames);
+	}
+
+	/**
+	 * Origins for a single hostname: the main domain plus each subdomain.
+	 */
+	fromHost(hostname: string): string[] {
+		return [
+			`${this.protocol}${hostname}`,
+			...this.subdomains.map((sub) => `${this.protocol}${sub}.${hostname}`)
+		];
+	}
+
+	/**
+	 * Origins for many hostnames, given either an array or a
+	 * comma-separated string.
+	 */
+	fromHosts(hostnames?: string | string[]) {
+		return this.parseList(hostnames).flatMap((hostname) =>
+			this.fromHost(hostname)
+		);
+	}
+
+	private parseList(hostnames?: string | string[]) {
+		if (Array.isArray(hostnames)) return hostnames;
+		return (
+			hostnames
+				?.split(',')
+				.map((hostname) => hostname.trim())
+				.filter(Boolean) || []
+		);
+	}
+}

package/templates/nest-api/files/src/common/misc/prisma.indicator.ts

@@ -0,0 +1,24 @@
+import { Injectable } from '@nestjs/common';
+import {
+	HealthIndicatorResult,
+	HealthIndicatorService
+} from '@nestjs/terminus';
+import { PrismaService } from 'common/services';
+
+@Injectable()
+export class PrismaHealthIndicator {
+	constructor(
+		private readonly db: PrismaService,
+		private readonly healthIndicatorService: HealthIndicatorService
+	) {}
+
+	async isHealthy(key: string): Promise<HealthIndicatorResult> {
+		const indicator = this.healthIndicatorService.check(key);
+		try {
+			await this.db.$queryRawUnsafe('SELECT 1');
+			return indicator.up();
+		} catch {
+			return indicator.down({ message: 'Database check failed' });
+		}
+	}
+}

package/templates/nest-api/files/src/common/modules/index.ts

@@ -0,0 +1,3 @@
+export * from './metrics.module'; // @feature observability
+export * from './logger.module';
+export * from './queue.module'; // @feature queue

package/templates/nest-api/files/src/common/modules/logger.module.ts

@@ -0,0 +1,104 @@
+import { Global, Module, RequestMethod } from '@nestjs/common';
+import { LoggerModule as PinoLoggerModule } from 'nestjs-pino';
+import { stdTimeFunctions, levels } from 'pino';
+import { IncomingMessage, ServerResponse } from 'http';
+import { CustomConfigService, GeneratorService } from 'common/services';
+import { LoggerService } from '../services';
+import {
+	PINO_CONSOLE_TARGET,
+	PINO_FILE_TARGET,
+	PINO_CONSOLE_TARGET_PROD
+} from '../constants';
+
+@Global()
+@Module({
+	imports: [
+		PinoLoggerModule.forRootAsync({
+			inject: [CustomConfigService, GeneratorService],
+			useFactory: async (
+				config: CustomConfigService,
+				gen: GeneratorService
+			) => ({
+				exclude: [
+					{ method: RequestMethod.ALL, path: 'health' },
+					{ method: RequestMethod.ALL, path: 'metrics' }
+				],
+				pinoHttp: {
+					level: config.logger.level,
+					transport:
+						config.app.env === 'production'
+							? { targets: [PINO_CONSOLE_TARGET_PROD, PINO_FILE_TARGET] }
+							: { targets: [PINO_CONSOLE_TARGET, PINO_FILE_TARGET] },
+					autoLogging: {
+						ignore: (req) => {
+							const path = (
+								(req as IncomingMessage & { originalUrl?: string })
+									.originalUrl ??
+								req.url ??
+								''
+							).split('?')[0];
+							const muted = [
+								'/dashboard',
+								'/openapi',
+								'/openapi-json',
+								'/docs',
+								'/metrics'
+							]; // Bull Board + API docs, all mounted outside Nest
+							return muted.some((p) => path === p || path.startsWith(p + '/'));
+						}
+					},
+					base: {
+						service: 'api',
+						env: config.app.env
+					},
+					genReqId: (req: IncomingMessage, res: ServerResponse) => {
+						const existing =
+							(req.headers['x-request-id'] as string | undefined) ??
+							(req as IncomingMessage & { id?: string }).id;
+						const id = existing ?? gen.cuid();
+						res.setHeader('X-Request-Id', id);
+						return id;
+					},
+					redact: {
+						paths: [
+							'req.headers.authorization',
+							'req.headers.cookie',
+							'req.headers["x-api-key"]',
+							'res.headers["set-cookie"]',
+							'*.password',
+							'*.token',
+							'*.secret'
+						],
+						censor: '[REDACTED]'
+					},
+					serializers: {
+						req(req) {
+							return { id: req.id, method: req.method, url: req.url };
+						},
+						res(res) {
+							return { statusCode: res.statusCode };
+						}
+					},
+					customLogLevel: (_req, res, err) => {
+						if (err || res.statusCode >= 500) return 'error';
+						if (res.statusCode >= 400) return 'warn';
+						return 'info';
+					},
+					customSuccessMessage: (req, res) =>
+						`${req.method} ${req.url} ${res.statusCode}`,
+					customErrorMessage: (req, res, err) =>
+						`${req.method} ${req.url} ${res.statusCode} ${
+							err?.message ?? ''
+						}`.trim(),
+					timestamp: stdTimeFunctions.isoTime,
+					mixin(_mergeObject, level) {
+						return { levelLabel: levels.labels[level] };
+					}
+				}
+			})
+		})
+	],
+	providers: [LoggerService],
+	exports: [LoggerService]
+})
+export class LoggerModule {}

package/templates/nest-api/files/src/common/modules/metrics.module.ts

@@ -0,0 +1,28 @@
+import { Module } from '@nestjs/common';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import {
+	makeHistogramProvider,
+	PrometheusModule
+} from '@willsoto/nestjs-prometheus';
+import { MetricsController } from '../controllers';
+import { MetricsInterceptor } from '../interceptors';
+
+@Module({
+	imports: [
+		PrometheusModule.register({
+			defaultLabels: { app: 'acme-api' },
+			defaultMetrics: { enabled: true },
+			controller: MetricsController
+		})
+	],
+	providers: [
+		makeHistogramProvider({
+			name: 'http_request_duration_seconds',
+			help: 'Duration of HTTP requests in seconds',
+			labelNames: ['method', 'route', 'status'],
+			buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5]
+		}),
+		{ provide: APP_INTERCEPTOR, useClass: MetricsInterceptor }
+	]
+})
+export class MetricsModule {}

package/templates/nest-api/files/src/common/modules/queue.module.ts

@@ -0,0 +1,23 @@
+import { Module } from '@nestjs/common';
+import { BullModule } from '@nestjs/bullmq';
+import { BullBoardModule } from '@bull-board/nestjs';
+import { BullMQAdapter } from '@bull-board/api/bullMQAdapter';
+
+@Module({})
+export class QueueModule {
+	static register(name: string) {
+		const queue = BullModule.registerQueue({ name });
+		const board = BullBoardModule.forFeature({
+			name,
+			adapter: BullMQAdapter
+		});
+
+		@Module({
+			imports: [queue, board],
+			exports: [queue, board]
+		})
+		class DynamicQueueModule {}
+
+		return DynamicQueueModule;
+	}
+}

package/templates/nest-api/files/src/common/processors/index.ts

@@ -0,0 +1 @@
+export * from './mail';

package/templates/nest-api/files/src/common/processors/mail/index.ts

@@ -0,0 +1,47 @@
+import { Injectable } from '@nestjs/common';
+import { Processor, WorkerHost, OnWorkerEvent } from '@nestjs/bullmq';
+import { Job } from 'bullmq';
+import { MailerService } from '@nestjs-modules/mailer';
+import { CustomConfigService, LoggerService } from 'common/services';
+import { EmailGlobalProps } from 'common/types';
+import { ProcessFactory } from './process';
+
+@Injectable()
+@Processor('mail')
+export class MailProcessor extends WorkerHost {
+	private readonly globals: EmailGlobalProps;
+
+	constructor(
+		private readonly config: CustomConfigService,
+		private readonly email: MailerService,
+		private readonly logger: LoggerService
+	) {
+		super();
+		this.globals = {
+			host: config.app.host,
+			appName: config.app.name,
+			footerText: `${config.app.name} - ${config.app.host}`
+		};
+	}
+
+	async process(job: Job<any, any, string>) {
+		const helper = ProcessFactory.init(job, this.globals);
+		if (helper) {
+			const options = helper.process();
+			await this.email.sendMail(options);
+		}
+	}
+
+	@OnWorkerEvent('completed')
+	onCompleted(job: Job<any, any, string>) {
+		this.logger.info({ jobId: job.id, jobName: job.name }, 'Mail sent.');
+	}
+
+	@OnWorkerEvent('failed')
+	onFailed(job: Job<any, any, string>, err: Error) {
+		this.logger.error(
+			{ err, jobId: job.id, jobName: job.name },
+			'Mail send failed.'
+		);
+	}
+}