Skip to main content

@ClientInfo()

Package: @nauth-toolkit/nestjs Type: Parameter Decorator

Parameter decorator that injects client information (IP address, user agent, device info) into controller methods.

Import from NestJS Package
import { ClientInfo } from '@nauth-toolkit/nestjs';

Overview​

The @ClientInfo() decorator provides a clean, type-safe way to access client metadata without manual extraction. Client information is automatically extracted by NAuthContextGuard and made available via this decorator.

Key Features:

  • Automatic IP address extraction (handles proxies/load balancers)
  • User agent parsing
  • Device token support
  • Optional geolocation data
  • Type-safe access to client metadata
note

Client information is automatically extracted by NAuthContextGuard when using AuthModule. No manual setup required.

Usage​

Full Client Info Object​

Get complete client information:

import { Controller, Post, Body } from '@nestjs/common';
import { ClientInfo, IClientInfo } from '@nauth-toolkit/nestjs';

@Controller('auth')
export class AuthController {
  @Post('login')
  async login(
    @Body() dto: LoginDTO,
    @ClientInfo() clientInfo: IClientInfo,
  ) {
    // clientInfo.ipAddress - automatically extracted
    // clientInfo.userAgent - automatically extracted
    // clientInfo.deviceToken - from request body or header (optional)
    return this.authService.login(dto, clientInfo);
  }
}

Specific Field​

Extract a specific field:

import { Controller, Post, Body } from '@nestjs/common';
import { ClientInfo } from '@nauth-toolkit/nestjs';

@Controller('auth')
export class AuthController {
  @Post('signup')
  async signup(
    @Body() dto: SignupDTO,
    @ClientInfo('ipAddress') ip: string,
  ) {
    // Just the IP address
    return this.authService.signup(dto, ip);
  }
}

With Authentication​

Use with authenticated routes:

import { Controller, Get, UseGuards } from '@nestjs/common';
import { AuthGuard, ClientInfo, CurrentUser } from '@nauth-toolkit/nestjs';
import type { IClientInfo, IUser } from '@nauth-toolkit/nestjs';

@Controller('profile')
@UseGuards(AuthGuard)
export class ProfileController {
  @Get('activity')
  getActivity(
    @CurrentUser() user: IUser,
    @ClientInfo() clientInfo: IClientInfo,
  ) {
    return {
      userId: user.sub,
      ipAddress: clientInfo.ipAddress,
      userAgent: clientInfo.userAgent,
      location: {
        country: clientInfo.ipCountry,
        city: clientInfo.ipCity,
      },
    };
  }
}

Client Info Interface​

interface IClientInfo {
  // Required
  ipAddress: string;          // Client IP (handles proxies/load balancers)
  userAgent: string;          // User-Agent header from the request

  // Optional — device
  origin?: string;            // HTTP Origin header
  deviceToken?: string;       // Trusted device token (cookie or X-Device-Token header)
  deviceName?: string;        // Device name supplied by the client
  deviceType?: 'mobile' | 'desktop' | 'tablet';

  // Optional — geolocation
  ipCountry?: string;
  ipCity?: string;
  ipLatitude?: number;
  ipLongitude?: number;

  // Optional — parsed user-agent
  platform?: string;          // e.g. "iOS", "Android", "Windows", "macOS"
  browser?: string;           // e.g. "Chrome", "Safari", "Firefox"

  // Optional — populated after JWT validation
  sessionId?: number;
  userId?: number;
  sub?: string;               // User UUID — prefer over userId for audit references
}

Field Access​

Access specific fields:

@Post('track')
async track(
  @ClientInfo('ipAddress') ip: string,
  @ClientInfo('userAgent') ua: string,
  @ClientInfo('ipCountry') country?: string,
) {
  // Use individual fields
}

Geolocation​

Geolocation data is automatically populated when GeoLocationService is configured:

@Post('login')
async login(
  @Body() dto: LoginDTO,
  @ClientInfo() clientInfo: IClientInfo,
) {
  if (clientInfo.ipCountry) {
    // Geolocation available
    console.log(`Login from ${clientInfo.ipCountry}`);
  }
}
Last updated on