Merge pull request #2 from codebuilderinc/feat/location-and-errors-endpoints

Author: digitalnomad91

.gitignore

@@ -54,3 +54,7 @@ pids
 
 # Diagnostic reports (https://nodejs.org/api/report.html)
 report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Sensitive / secrets (override earlier negation)
+.vscode/settings.json
+google-service-account-key.json

README.md

@@ -99,3 +99,61 @@ Nest is an MIT-licensed open source project. It can grow thanks to the sponsors
 ## License
 
 Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE).
+
+## API Conventions
+
+### Response Envelope
+
+Endpoints using the custom `@Api({ envelope: true })` decorator option return:
+
+```
+{ "success": true, "data": <payload> }
+```
+
+Errors are normalized by the global `HttpExceptionFilter` into:
+
+```
+{
+  "success": false,
+  "error": {
+    "statusCode": 400,
+    "message": "Validation failed",
+    "details": {},
+    "path": "/endpoint",
+    "timestamp": "2025-01-01T00:00:00.000Z"
+  }
+}
+```
+
+### Pagination Shape
+
+Paginated endpoints (with `paginatedResponseType`) return (inside the envelope when enabled):
+
+```
+{
+  "items": [ ... ],
+  "pageInfo": {
+    "hasNextPage": true,
+    "hasPreviousPage": false,
+    "startCursor": "0",
+    "endCursor": "25"
+  },
+  "totalCount": 1234,
+  "meta": { "company": { ... } }
+}
+```
+
+Use `buildPaginatedResult({ items, skip, take, totalCount, meta })` in services.
+
+### Automatic Swagger Params
+
+Annotate DTO properties with `@Field({ inQuery: true })` or `@Field({ inPath: true })`. Add those DTOs to `queriesFrom` / `pathParamsFrom` in `@Api()` and Swagger params are generated automatically.
+
+### Adding a New Paginated Endpoint
+1. Create / reuse DTOs + annotate filters & pagination args with `@Field`.
+2. Controller: `@Api({ paginatedResponseType: MyDto, envelope: true, queriesFrom: [PaginationArgs, FilterDto] })`.
+3. Service: return `buildPaginatedResult`.
+
+### Error Handling
+Throw standard Nest `HttpException` subclasses. The filter wraps them in the envelope. Custom non-Http errors can be mapped by extending the filter if needed.
+

package.json

@@ -9,7 +9,7 @@
     "build": "nest build",
     "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
     "start": "nest start",
-    "start:dev": "nest start --watch",
+    "start:dev": "NODE_ENV=local nest start --watch",
     "start:debug": "nest start --debug --watch",
     "start:prod": "node dist/main",
     "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",

src/app.controller.ts

@@ -1,12 +1,14 @@
 import { Controller, Get } from '@nestjs/common';
 import { AppService } from './app.service';
+import { Api } from './common/decorators/api.decorator';
 
 @Controller()
 export class AppController {
   constructor(private readonly appService: AppService) {}
 
   @Get()
-  getHello(): string {
-    return this.appService.getHello();
+  @Api({ summary: 'Health / hello endpoint', description: 'Simple hello world response', envelope: true })
+  getHello() {
+    return { message: this.appService.getHello() };
   }
 }

src/app.module.ts

@@ -15,6 +15,9 @@ import { EventsModule } from './events/events.module';
 import { OpenTelemetryModule } from 'nestjs-otel';
 import { LoggerModule } from './logger/logger.module';
 import { RedisModule } from './common/redis/redis.module';
+import { NotificationsModule } from './notifications/notifications.module';
+import { LocationModule } from './location/location.module';
+import { ErrorsModule } from './errors/errors.module';
 
 //import { ConfigModule } from '@nestjs/config';
 //import { AppResolver } from './app.resolver';
@@ -74,6 +77,9 @@ const OpenTelemetryModuleConfig = OpenTelemetryModule.forRoot({
     //RedisModule,
 
     WssModule,
+    NotificationsModule,
+    LocationModule,
+    ErrorsModule,
   ],
   providers: [],
 })

src/auth/auth.controller.ts

@@ -1,8 +1,8 @@
 import { Body, Controller, Post, HttpCode, HttpStatus, BadRequestException } from '@nestjs/common';
 import { AuthService } from './auth.service';
 import { GoogleAuthInput } from './dto/google-auth.input';
-import { ApiTags, ApiOperation, ApiResponse, ApiParam } from '@nestjs/swagger';
-import { ApiPaginationQuery } from '../common/decorators/api-nested-query.decorator';
+import { ApiTags } from '@nestjs/swagger';
+import { Api } from '../common/decorators/api.decorator';
 
 @ApiTags('Auth')
 @Controller('auth')
@@ -13,12 +13,16 @@ export class AuthController {
    * Fetch new jobs from Reddit and Web3Career, store them, and send notifications
    */
   @Post('google')
-  @ApiOperation({
-    summary: 'Fetch new jobs from Reddit and Web3Career',
-    description: 'Fetches new jobs from both sources, stores them, and sends notifications.',
+  @Api({
+    summary: 'Google authentication',
+    description: 'Authenticate a user using a Google ID token and optional buildType.',
+    bodyType: GoogleAuthInput,
+    envelope: true,
+    responses: [
+      { status: 200, description: 'Authenticated successfully.' },
+      { status: 400, description: 'ID token missing or invalid.' },
+    ],
   })
-  @ApiParam({ name: 'idToken', description: 'Google ID Token', type: String })
-  @ApiResponse({ status: 200, description: 'Jobs fetched and notifications sent.' })
   @HttpCode(HttpStatus.OK)
   async googleAuth(@Body() googleAuthInput: GoogleAuthInput) {
     const { idToken, buildType } = googleAuthInput;

src/common/configs/config.helper.ts

@@ -5,18 +5,51 @@ import { ApplicationConfig, Config } from './config.interface';
 import config from './config';
 
 export function loadConfig() {
-  const filePath = `.env`; //${process.env.NODE_ENV || 'local'}
+  // Determine which env file to load. Precedence:
+  // 1. Explicit ENV_FILE var
+  // 2. NODE_ENV=local|development -> .env.local (if exists)
+  // 3. Fallback to .env
+  const explicit = process.env.ENV_FILE;
+  const nodeEnv = (process.env.NODE_ENV || '').toLowerCase();
+  const candidates: string[] = [];
+  if (explicit) {
+    candidates.push(explicit);
+  } else if (['local', 'development', 'dev'].includes(nodeEnv)) {
+    candidates.push('.env.local');
+  }
+  candidates.push('.env');
+
+  let pickedPath = '.env';
+  for (const c of candidates) {
+    if (fs.existsSync(c)) {
+      pickedPath = c;
+      break;
+    }
+  }
 
-  // Try to read and parse the file
   let file = Buffer.from('');
   try {
-    file = fs.readFileSync(filePath);
+    file = fs.readFileSync(pickedPath);
   } catch {
-    /* empty */
+    // If nothing found we proceed with empty buffer relying on process.env
   }
 
   const dotenvConfig = dotenv.parse(file);
 
+  // Inject parsed values into process.env if not already present so the rest of the
+  // application (e.g. main.ts reading process.env.PORT) sees them.
+  for (const [k, v] of Object.entries(dotenvConfig)) {
+    if (process.env[k] === undefined) {
+      process.env[k] = v;
+    }
+  }
+
+  if (!process.env.ENV_FILE_LOGGED) {
+    // Single log guard to avoid spamming on hot-reload
+    console.log(`[config] Loaded environment file: ${pickedPath}`);
+    process.env.ENV_FILE_LOGGED = 'true';
+  }
+
   // Parse nested JSON in file and merge with process.env
   const parsedConfig = parseNestedJson({
     ...dotenvConfig,

src/common/configs/config.ts

@@ -2,7 +2,7 @@ import type { Config } from './config.interface';
 
 const config: Config = {
   nest: {
-    port: 3000,
+    port: 4000,
   },
   cors: {
     enabled: true,