@vritti/api-sdk 0.1.6 → 0.1.8

package/dist/index.d.ts

@@ -511,6 +511,52 @@ declare class VrittiAuthGuard implements CanActivate {
      * @throws UnauthorizedException if token binding validation fails
      */
     private validateRefreshTokenBinding;
+    /**
+     * Validate CSRF token for state-changing requests
+     * Uses Fastify's csrf-protection plugin for token validation
+     *
+     * @param request - Fastify request object
+     * @param reply - Fastify reply object
+     * @throws ForbiddenException if CSRF validation fails
+     */
+    private validateCsrf;
+}
+
+/**
+ * SSE Authentication Guard - For Server-Sent Events endpoints
+ *
+ * This guard is specifically designed for SSE endpoints where:
+ * 1. Browser's EventSource API cannot send custom headers
+ * 2. Token must be passed via query parameter
+ * 3. CORS headers must be set before any response (including errors)
+ *
+ * Validation Flow:
+ * 1. Set CORS headers FIRST (ensures error responses include CORS)
+ * 2. Extract token from query param (?token=<jwt>)
+ * 3. Validate token is type='onboarding'
+ * 4. Attach user data to request.user
+ *
+ * Usage:
+ * ```typescript
+ * @Sse('events')
+ * @Public() // Bypass global VrittiAuthGuard
+ * @UseGuards(SseAuthGuard)
+ * async subscribeToEvents(@UserId() userId: string) { ... }
+ * ```
+ *
+ * Note: Must be used with @Public() to bypass the global VrittiAuthGuard
+ * since EventSource cannot send Authorization headers.
+ */
+declare class SseAuthGuard implements CanActivate {
+    private readonly jwtService;
+    private readonly logger;
+    constructor(jwtService: JwtService);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    /**
+     * Set CORS headers for SSE responses
+     * Must be called before any potential exceptions
+     */
+    private setCorsHeaders;
 }
 
 /**
@@ -1614,21 +1660,87 @@ declare abstract class TenantBaseRepository<TTable extends PgTable, TInsert = In
     exists(where: SQL): Promise<boolean>;
 }
 
+/**
+ * RFC 9457 Problem Details field-specific error structure.
+ *
+ * Used for validation errors or other field-specific issues.
+ * The `field` property is required to ensure clear association.
+ */
 interface FieldError {
-    field?: string;
+    /** The field name (e.g., 'email', 'password') - REQUIRED */
+    field: string;
+    /** The error message for this field */
     message: string;
 }
+/**
+ * RFC 9457 Problem Details standard fields.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9457.html
+ */
 interface ProblemDetails {
+    /** Problem type URI (default: "about:blank") */
+    type: string;
+    /** HTTP status phrase (e.g., "Unauthorized", "Not Found") */
     title: string;
+    /** HTTP status code */
     status: number;
+    /** Root error heading (extension member, maps to AlertTitle in frontend) */
+    label?: string;
+    /** Detailed error description (maps to AlertDescription in frontend) */
     detail: string;
+    /** Request path where the error occurred */
+    instance?: string;
 }
+/**
+ * Complete API error response following RFC 9457 Problem Details format.
+ *
+ * Extends ProblemDetails with field-specific errors.
+ */
 interface ApiErrorResponse extends ProblemDetails {
+    /** Field-specific errors (field is required in each FieldError) */
     errors: FieldError[];
 }
 
-declare abstract class BaseFieldException extends HttpException {
-    constructor(statusOrMessageOrErrors: HttpStatus | string | FieldError[], messageOrStatus?: string | HttpStatus, statusOrDetail?: HttpStatus | string, detail?: string);
+/**
+ * Options for creating RFC 9457 Problem Details exceptions.
+ *
+ * @example
+ * throw new UnauthorizedException({
+ *   label: 'Invalid Credentials',
+ *   detail: 'The email or password is incorrect',
+ * });
+ *
+ * @example
+ * throw new BadRequestException({
+ *   detail: 'Validation failed',
+ *   errors: [
+ *     { field: 'email', message: 'Invalid email format' },
+ *     { field: 'password', message: 'Password too short' },
+ *   ],
+ * });
+ */
+interface ProblemOptions {
+    /** Problem type URI (default: "about:blank") */
+    type?: string;
+    /** Root error heading (maps to AlertTitle in frontend) */
+    label?: string;
+    /** Root error description (maps to AlertDescription in frontend) */
+    detail?: string;
+    /** Field-specific errors only (field is required) */
+    errors?: FieldError[];
+}
+/**
+ * Base exception class that follows RFC 9457 Problem Details format.
+ *
+ * Provides a clean interface for creating HTTP exceptions with:
+ * - RFC 9457 standard fields (type, title, status, detail, instance)
+ * - Extension members (label for root error heading, errors for field-specific errors)
+ *
+ * The `title` field is always set to the HTTP status phrase (e.g., "Unauthorized")
+ * by the HttpExceptionFilter, not by this class.
+ */
+declare abstract class HttpProblemException extends HttpException {
+    constructor(detailOrOptions: string | ProblemOptions, httpStatus: HttpStatus);
 }
 
 /**
@@ -1637,21 +1749,17 @@ declare abstract class BaseFieldException extends HttpException {
  *
  * @example
  * // Simple message
- * throw new BadGatewayException('Bad gateway');
- *
- * // Field-specific error
- * throw new BadGatewayException('upstream', 'Upstream service returned invalid response');
- *
- * // With detail
- * throw new BadGatewayException('proxy', 'Gateway error', 'Payment service is not responding correctly');
+ * throw new BadGatewayException('Upstream service returned invalid response');
  *
- * // Multiple field errors
- * throw new BadGatewayException([
- *   { field: 'gateway', message: 'Invalid response from upstream server' }
- * ]);
+ * // With options
+ * throw new BadGatewayException({
+ *   title: 'Upstream Service Error',
+ *   detail: 'The payment service is not responding correctly',
+ *   instance: '/api/payments/process',
+ * });
  */
-declare class BadGatewayException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class BadGatewayException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -1661,20 +1769,24 @@ declare class BadGatewayException extends BaseFieldException {
  * // Simple message
  * throw new BadRequestException('Invalid request data');
  *
- * // Field-specific error
- * throw new BadRequestException('email', 'Invalid email format');
- *
- * // With detail
- * throw new BadRequestException('email', 'Invalid email format', 'Email must be in valid format');
+ * // With field errors
+ * throw new BadRequestException({
+ *   detail: 'Validation failed',
+ *   errors: [
+ *     { field: 'email', message: 'Invalid email format' },
+ *     { field: 'password', message: 'Password too short' }
+ *   ]
+ * });
  *
- * // Multiple field errors
- * throw new BadRequestException([
- *   { field: 'email', message: 'Invalid email' },
- *   { field: 'password', message: 'Password too short' }
- * ]);
+ * // With custom label and type
+ * throw new BadRequestException({
+ *   label: 'Invalid Form Data',
+ *   detail: 'Please check your input',
+ *   type: 'validation-error'
+ * });
  */
-declare class BadRequestException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class BadRequestException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -1682,44 +1794,56 @@ declare class BadRequestException extends BaseFieldException {
  * Commonly used for duplicate resources or concurrent modification issues.
  *
  * @example
- * // Simple message
+ * // Simple detail message
  * throw new ConflictException('Resource already exists');
  *
- * // Field-specific error
- * throw new ConflictException('email', 'Email already registered');
+ * // With custom label and detail
+ * throw new ConflictException({
+ *   label: 'Duplicate Entry',
+ *   detail: 'Email already exists',
+ * });
  *
- * // With detail
- * throw new ConflictException('email', 'Email already exists', 'Try logging in instead');
+ * // With field-specific errors
+ * throw new ConflictException({
+ *   detail: 'Duplicate data detected',
+ *   errors: [
+ *     { field: 'email', message: 'Email already registered' }
+ *   ],
+ * });
  *
- * // Multiple field errors
- * throw new ConflictException([
- *   { field: 'email', message: 'Email already in use' }
- * ]);
+ * // With custom label and field errors
+ * throw new ConflictException({
+ *   label: 'Resource Conflict',
+ *   detail: 'Try logging in instead or use a different email',
+ *   errors: [{ field: 'email', message: 'Email already in use' }],
+ * });
  */
-declare class ConflictException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class ConflictException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
  * Exception thrown when the user does not have permission to access a resource (HTTP 403).
  *
  * @example
- * // Simple message
+ * // Simple detail message
  * throw new ForbiddenException('Access denied');
  *
- * // Field-specific error
- * throw new ForbiddenException('resource', 'You do not have permission');
- *
- * // With detail
- * throw new ForbiddenException('resource', 'Access denied', 'Admin role required');
+ * // With custom label
+ * throw new ForbiddenException({
+ *   label: 'Access Denied',
+ *   detail: 'You do not have permission to perform this action',
+ * });
  *
- * // Multiple field errors
- * throw new ForbiddenException([
- *   { field: 'action', message: 'Insufficient permissions' }
- * ]);
+ * // With field-specific errors
+ * throw new ForbiddenException({
+ *   label: 'Permission Denied',
+ *   detail: 'Contact your administrator for access',
+ *   errors: [{ field: 'role', message: 'Admin role required' }],
+ * });
  */
-declare class ForbiddenException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class ForbiddenException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -1730,19 +1854,21 @@ declare class ForbiddenException extends BaseFieldException {
  * // Simple message
  * throw new GoneException('Resource permanently deleted');
  *
- * // Field-specific error
- * throw new GoneException('account', 'Account has been permanently deleted');
- *
- * // With detail
- * throw new GoneException('account', 'Deleted', 'This account was removed on user request');
+ * // With label and detail
+ * throw new GoneException({
+ *   label: 'Account Deleted',
+ *   detail: 'This account has been permanently removed',
+ * });
  *
- * // Multiple field errors
- * throw new GoneException([
- *   { field: 'resource', message: 'This content has been permanently removed' }
- * ]);
+ * // With field errors
+ * throw new GoneException({
+ *   label: 'Resource Removed',
+ *   detail: 'The resource was removed due to policy violation',
+ *   errors: [{ field: 'resource', message: 'This content has been permanently deleted' }],
+ * });
  */
-declare class GoneException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class GoneException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -1752,19 +1878,15 @@ declare class GoneException extends BaseFieldException {
  * // Simple message
  * throw new InternalServerErrorException('An unexpected error occurred');
  *
- * // Field-specific error
- * throw new InternalServerErrorException('database', 'Database connection failed');
- *
- * // With detail
- * throw new InternalServerErrorException('database', 'Connection failed', 'Please try again later');
- *
- * // Multiple field errors
- * throw new InternalServerErrorException([
- *   { field: 'system', message: 'Internal error' }
- * ]);
+ * // With options object
+ * throw new InternalServerErrorException({
+ *   title: 'Server Error',
+ *   detail: 'Something went wrong',
+ *   instance: '/api/users',
+ * });
  */
-declare class InternalServerErrorException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class InternalServerErrorException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -1775,19 +1897,28 @@ declare class InternalServerErrorException extends BaseFieldException {
  * // Simple message
  * throw new MethodNotAllowedException('Method not allowed');
  *
- * // Field-specific error
- * throw new MethodNotAllowedException('method', 'POST method not allowed on this endpoint');
- *
  * // With detail
- * throw new MethodNotAllowedException('method', 'Not allowed', 'Only GET and PUT are supported');
+ * throw new MethodNotAllowedException({
+ *   detail: 'Method not allowed',
+ *   instance: '/api/resource/123'
+ * });
+ *
+ * // With custom title
+ * throw new MethodNotAllowedException({
+ *   title: 'Invalid HTTP Method',
+ *   detail: 'This endpoint only supports GET requests',
+ * });
  *
- * // Multiple field errors
- * throw new MethodNotAllowedException([
- *   { field: 'method', message: 'DELETE is not allowed on this resource' }
- * ]);
+ * // With additional context
+ * throw new MethodNotAllowedException({
+ *   title: 'Unsupported Operation',
+ *   detail: 'PATCH is not supported for this resource',
+ *   instance: '/api/users/456',
+ *   extensions: { allowedMethods: ['GET', 'PUT', 'DELETE'] }
+ * });
  */
-declare class MethodNotAllowedException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class MethodNotAllowedException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -1795,22 +1926,34 @@ declare class MethodNotAllowedException extends BaseFieldException {
  * Used when the server cannot produce a response matching the Accept headers.
  *
  * @example
- * // Simple message
+ * // Simple detail message
  * throw new NotAcceptableException('Requested format not available');
  *
- * // Field-specific error
- * throw new NotAcceptableException('accept', 'Cannot produce response in requested format');
+ * // With custom label
+ * throw new NotAcceptableException({
+ *   label: 'Content Negotiation Failed',
+ *   detail: 'Cannot produce response in the requested format',
+ * });
  *
- * // With detail
- * throw new NotAcceptableException('accept', 'Format not supported', 'Only JSON is available');
+ * // With field-specific errors
+ * throw new NotAcceptableException({
+ *   detail: 'Requested format is not supported',
+ *   errors: [
+ *     { field: 'accept', message: 'XML format is not available' },
+ *     { field: 'contentType', message: 'Only JSON is supported' },
+ *   ],
+ * });
  *
- * // Multiple field errors
- * throw new NotAcceptableException([
- *   { field: 'contentType', message: 'XML format is not supported' }
- * ]);
+ * // With all options
+ * throw new NotAcceptableException({
+ *   type: 'https://api.example.com/errors/format-not-supported',
+ *   label: 'Unsupported Media Type',
+ *   detail: 'This API only supports JSON responses',
+ *   errors: [{ field: 'accept', message: 'XML format is not available' }],
+ * });
  */
-declare class NotAcceptableException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class NotAcceptableException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -1820,19 +1963,20 @@ declare class NotAcceptableException extends BaseFieldException {
  * // Simple message
  * throw new NotFoundException('Resource not found');
  *
- * // Field-specific error
- * throw new NotFoundException('userId', 'User not found');
- *
- * // With detail
- * throw new NotFoundException('userId', 'User not found', 'No user exists with the provided ID');
+ * // With custom label and detail
+ * throw new NotFoundException({
+ *   label: 'User Not Found',
+ *   detail: 'The requested user does not exist',
+ * });
  *
- * // Multiple field errors
- * throw new NotFoundException([
- *   { field: 'userId', message: 'User does not exist' }
- * ]);
+ * // With field errors
+ * throw new NotFoundException({
+ *   detail: 'The requested resource could not be located',
+ *   errors: [{ field: 'userId', message: 'User does not exist' }],
+ * });
  */
-declare class NotFoundException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class NotFoundException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -1843,19 +1987,14 @@ declare class NotFoundException extends BaseFieldException {
  * // Simple message
  * throw new NotImplementedException('Feature not yet implemented');
  *
- * // Field-specific error
- * throw new NotImplementedException('feature', 'This feature is coming soon');
- *
- * // With detail
- * throw new NotImplementedException('export', 'Not implemented', 'PDF export will be available in v2.0');
- *
- * // Multiple field errors
- * throw new NotImplementedException([
- *   { field: 'functionality', message: 'This functionality is not available yet' }
- * ]);
+ * // With options
+ * throw new NotImplementedException({
+ *   detail: 'This feature is coming soon',
+ *   instance: '/api/v1/export',
+ * });
  */
-declare class NotImplementedException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class NotImplementedException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -1866,19 +2005,21 @@ declare class NotImplementedException extends BaseFieldException {
  * // Simple message
  * throw new PayloadTooLargeException('Request payload too large');
  *
- * // Field-specific error
- * throw new PayloadTooLargeException('file', 'File size exceeds maximum allowed');
- *
  * // With detail
- * throw new PayloadTooLargeException('file', 'File too large', 'Maximum size is 10MB');
+ * throw new PayloadTooLargeException({
+ *   detail: 'Request payload too large',
+ *   instance: '/api/upload',
+ * });
  *
- * // Multiple field errors
- * throw new PayloadTooLargeException([
- *   { field: 'upload', message: 'File exceeds 10MB limit' }
- * ]);
+ * // With custom title
+ * throw new PayloadTooLargeException({
+ *   title: 'File Size Limit Exceeded',
+ *   detail: 'The uploaded file is too large. Maximum size is 10MB',
+ *   instance: '/api/files/upload',
+ * });
  */
-declare class PayloadTooLargeException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class PayloadTooLargeException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -1889,19 +2030,21 @@ declare class PayloadTooLargeException extends BaseFieldException {
  * // Simple message
  * throw new RequestTimeoutException('Request timeout');
  *
- * // Field-specific error
- * throw new RequestTimeoutException('operation', 'Operation timed out');
- *
- * // With detail
- * throw new RequestTimeoutException('query', 'Database query timeout', 'Try with fewer filters');
+ * // With custom title and detail
+ * throw new RequestTimeoutException({
+ *   title: 'Operation Timeout',
+ *   detail: 'The request took too long to complete',
+ * });
  *
- * // Multiple field errors
- * throw new RequestTimeoutException([
- *   { field: 'processing', message: 'Request took too long to complete' }
- * ]);
+ * // With instance for tracking
+ * throw new RequestTimeoutException({
+ *   title: 'Database Timeout',
+ *   detail: 'Query execution exceeded time limit',
+ *   instance: '/api/queries/123',
+ * });
  */
-declare class RequestTimeoutException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class RequestTimeoutException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -1912,19 +2055,21 @@ declare class RequestTimeoutException extends BaseFieldException {
  * // Simple message
  * throw new ServiceUnavailableException('Service temporarily unavailable');
  *
- * // Field-specific error
- * throw new ServiceUnavailableException('service', 'Scheduled maintenance in progress');
- *
- * // With detail
- * throw new ServiceUnavailableException('service', 'Maintenance', 'Service will be back at 2 PM EST');
+ * // With custom title and detail
+ * throw new ServiceUnavailableException({
+ *   title: 'Scheduled Maintenance',
+ *   detail: 'Expected completion: 2 PM EST',
+ * });
  *
- * // Multiple field errors
- * throw new ServiceUnavailableException([
- *   { field: 'database', message: 'Database is temporarily unavailable' }
- * ]);
+ * // With field errors
+ * throw new ServiceUnavailableException({
+ *   title: 'External Service Unavailable',
+ *   detail: 'Payment service is down',
+ *   errors: [{ field: 'paymentGateway', message: 'Payment gateway unavailable' }],
+ * });
  */
-declare class ServiceUnavailableException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class ServiceUnavailableException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -1935,19 +2080,30 @@ declare class ServiceUnavailableException extends BaseFieldException {
  * // Simple message
  * throw new TooManyRequestsException('Too many requests');
  *
- * // Field-specific error
- * throw new TooManyRequestsException('api', 'Rate limit exceeded');
+ * // With custom title and detail
+ * throw new TooManyRequestsException({
+ *   title: 'Rate Limit Exceeded',
+ *   detail: 'You have exceeded the allowed number of requests',
+ * });
  *
- * // With detail
- * throw new TooManyRequestsException('api', 'Rate limit exceeded', 'Try again in 60 seconds');
+ * // With field errors
+ * throw new TooManyRequestsException({
+ *   title: 'API Throttled',
+ *   detail: 'Too many requests to this endpoint',
+ *   errors: [{ field: 'requests', message: 'Rate limit exceeded' }],
+ * });
  *
- * // Multiple field errors
- * throw new TooManyRequestsException([
- *   { field: 'requests', message: 'Rate limit exceeded for this endpoint' }
- * ]);
+ * // With instance and additional metadata
+ * throw new TooManyRequestsException({
+ *   detail: 'Rate limit exceeded',
+ *   instance: '/api/v1/users',
+ *   retryAfter: 60,
+ *   limit: 100,
+ *   remaining: 0,
+ * });
  */
-declare class TooManyRequestsException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class TooManyRequestsException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -1957,19 +2113,14 @@ declare class TooManyRequestsException extends BaseFieldException {
  * // Simple message
  * throw new UnauthorizedException('Authentication required');
  *
- * // Field-specific error
- * throw new UnauthorizedException('token', 'Invalid or expired token');
- *
- * // With detail
- * throw new UnauthorizedException('token', 'Invalid token', 'Please login again');
- *
- * // Multiple field errors
- * throw new UnauthorizedException([
- *   { field: 'token', message: 'Token expired' }
- * ]);
+ * // With problem details
+ * throw new UnauthorizedException({
+ *   detail: 'Invalid or expired token',
+ *   instance: '/api/auth/verify'
+ * });
  */
-declare class UnauthorizedException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class UnauthorizedException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -1980,20 +2131,32 @@ declare class UnauthorizedException extends BaseFieldException {
  * // Simple message
  * throw new UnprocessableEntityException('Cannot process the request');
  *
- * // Field-specific error
- * throw new UnprocessableEntityException('age', 'Age must be 18 or older');
- *
  * // With detail
- * throw new UnprocessableEntityException('quantity', 'Insufficient stock', 'Only 5 items available');
+ * throw new UnprocessableEntityException({
+ *   detail: 'Cannot process the order due to stock limitations',
+ * });
+ *
+ * // With custom title
+ * throw new UnprocessableEntityException({
+ *   title: 'Business Rule Violation',
+ *   detail: 'Cannot process the order due to stock limitations',
+ * });
  *
- * // Multiple field errors
- * throw new UnprocessableEntityException([
- *   { field: 'startDate', message: 'Start date must be before end date' },
- *   { field: 'endDate', message: 'End date cannot be in the past' }
- * ]);
+ * // With field errors
+ * throw new UnprocessableEntityException({
+ *   detail: 'One or more items exceed available inventory',
+ *   errors: [{ field: 'quantity', message: 'Insufficient stock available' }],
+ * });
+ *
+ * // With custom title and field errors
+ * throw new UnprocessableEntityException({
+ *   title: 'Validation Failed',
+ *   detail: 'One or more items exceed available inventory',
+ *   errors: [{ field: 'quantity', message: 'Insufficient stock available' }],
+ * });
  */
-declare class UnprocessableEntityException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class UnprocessableEntityException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -2004,19 +2167,21 @@ declare class UnprocessableEntityException extends BaseFieldException {
  * // Simple message
  * throw new UnsupportedMediaTypeException('Unsupported media type');
  *
- * // Field-specific error
- * throw new UnsupportedMediaTypeException('contentType', 'XML is not supported');
- *
- * // With detail
- * throw new UnsupportedMediaTypeException('contentType', 'Not supported', 'Only JSON and form-data are accepted');
+ * // With label and detail
+ * throw new UnsupportedMediaTypeException({
+ *   label: 'Invalid Content Type',
+ *   detail: 'The content type is not supported',
+ * });
  *
- * // Multiple field errors
- * throw new UnsupportedMediaTypeException([
- *   { field: 'contentType', message: 'application/xml is not supported' }
- * ]);
+ * // With field errors
+ * throw new UnsupportedMediaTypeException({
+ *   label: 'Unsupported File Format',
+ *   detail: 'Accepted formats: JPEG, PNG, GIF',
+ *   errors: [{ field: 'file', message: 'PDF format is not accepted for this upload' }],
+ * });
  */
-declare class UnsupportedMediaTypeException extends BaseFieldException {
-    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+declare class UnsupportedMediaTypeException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -2024,20 +2189,36 @@ declare class UnsupportedMediaTypeException extends BaseFieldException {
  * Typically used for form validation or DTO validation errors.
  *
  * @example
- * // Multiple validation errors
- * throw new ValidationException([
- *   { field: 'email', message: 'Invalid email format' },
- *   { field: 'password', message: 'Password must be at least 8 characters' }
- * ]);
+ * // Simple message
+ * throw new ValidationException('Validation failed');
  *
- * // With detail
- * throw new ValidationException(
- *   [{ field: 'email', message: 'Invalid format' }],
- *   'Please correct the errors and try again'
- * );
+ * // With custom label and detail
+ * throw new ValidationException({
+ *   label: 'Invalid Input',
+ *   detail: 'The provided data is invalid',
+ * });
+ *
+ * // With field-specific errors
+ * throw new ValidationException({
+ *   detail: 'Please correct the highlighted fields',
+ *   errors: [
+ *     { field: 'email', message: 'Invalid email format' },
+ *     { field: 'password', message: 'Password must be at least 8 characters' }
+ *   ],
+ * });
+ *
+ * // With custom label and field errors
+ * throw new ValidationException({
+ *   label: 'Form Validation Failed',
+ *   detail: 'Please correct the highlighted fields',
+ *   errors: [
+ *     { field: 'email', message: 'Invalid email format' },
+ *     { field: 'password', message: 'Password too weak' }
+ *   ],
+ * });
  */
-declare class ValidationException extends BaseFieldException {
-    constructor(errors: FieldError[], detail?: string);
+declare class ValidationException extends HttpProblemException {
+    constructor(detailOrOptions?: string | ProblemOptions);
 }
 
 /**
@@ -2054,18 +2235,21 @@ declare class ValidationException extends BaseFieldException {
  */
 declare function getHttpStatusTitle(status: number): string;
 /**
- * Global HTTP Exception Filter implementing RFC 7807 Problem Details
+ * Global HTTP Exception Filter implementing RFC 9457 Problem Details
  *
- * Transforms all exceptions into a standardized RFC 7807 format:
+ * Transforms all exceptions into a standardized RFC 9457 format:
  * {
- *   title: string,        // Human-readable status title
+ *   type: string,         // Problem type URI (default: "about:blank")
+ *   title: string,        // HTTP status phrase (e.g., "Unauthorized")
  *   status: number,       // HTTP status code
- *   detail: string,       // Detailed error description
- *   errors: FieldError[]  // Field-specific error messages
+ *   label?: string,       // Root error heading (maps to AlertTitle)
+ *   detail: string,       // Root error description (maps to AlertDescription)
+ *   instance: string,     // Request path
+ *   errors: FieldError[]  // Field-specific errors (field is required)
  * }
  *
  * Handles:
- * - Custom field exceptions from @vritti/api-sdk (BaseFieldException)
+ * - Custom HttpProblemException from @vritti/api-sdk
  * - Class-validator DTO validation errors
  * - Standard NestJS HTTP exceptions
  * - Unknown errors
@@ -2075,44 +2259,38 @@ declare class HttpExceptionFilter implements ExceptionFilter {
     catch(exception: unknown, host: ArgumentsHost): void;
 }
 
+declare const SKIP_CSRF_KEY = "skipCsrf";
 /**
- * CSRF Guard
- *
- * Global guard that automatically protects all state-changing requests (POST, PUT, PATCH, DELETE)
- * from CSRF attacks using Fastify's csrf-protection plugin.
- *
- * Flow:
- * 1. Skip safe methods (GET, HEAD, OPTIONS)
- * 2. Skip endpoints marked with @Public()
- * 3. Validate CSRF token for all other requests
+ * Decorator to skip CSRF validation for specific routes or controllers.
+ * Use this for webhook endpoints that receive requests from external services
+ * (e.g., WhatsApp, Twilio) which cannot include CSRF tokens.
  *
- * Token Sources (in priority order by @fastify/csrf-protection):
- * 1. req.headers['csrf-token']
- * 2. req.headers['xsrf-token']
- * 3. req.headers['x-csrf-token']
- * 4. req.headers['x-xsrf-token']
- * 5. req.body._csrf
+ * @example
+ * // Skip CSRF for entire controller
+ * @Controller('webhooks')
+ * @SkipCsrf()
+ * export class WebhookController { ... }
  *
- * This guard should be registered globally in main.ts after CSRF plugin registration.
+ * @example
+ * // Skip CSRF for specific route
+ * @Post()
+ * @SkipCsrf()
+ * async handleWebhook() { ... }
  */
-declare class CsrfGuard implements CanActivate {
-    private readonly logger;
-    canActivate(context: ExecutionContext): Promise<boolean>;
-}
+declare const SkipCsrf: () => _nestjs_common.CustomDecorator<string>;
 
 /**
- * HTTP Module
- *
- * Provides HTTP utilities including:
- * - CSRF Guard for request protection
- * - HTTP Exception Filter for standardized error responses
- *
- * Usage:
- * Import this module to access HTTP guards and filters.
- * Guards and filters are registered globally in the main application.
+ * Extract ISO country code from E.164 phone number
+ * @param phone Phone number in E.164 format (e.g., +919876543210)
+ * @returns ISO 3166-1 alpha-2 country code (e.g., "IN") or undefined
  */
-declare class HttpModule {
-}
+declare function extractCountryFromPhone(phone: string): string | undefined;
+/**
+ * Normalize phone number to E.164 format with + prefix
+ * @param phone Phone number (with or without + prefix)
+ * @returns Phone number in E.164 format
+ */
+declare function normalizePhoneNumber(phone: string): string;
 
 /**
  * Supported log levels for the logging system.
@@ -2515,4 +2693,4 @@ declare function generateCorrelationId(): string;
  */
 declare function addCorrelationIdToResponse(reply: FastifyReply, correlationId: string, headerName?: string): void;
 
-export { type ApiErrorResponse, type ApiSdkConfig, AuthConfigModule, BadGatewayException, BadRequestException, BaseFieldException, ConflictException, type CookieConfig, type CorrelationContext, CorrelationIdMiddleware, CsrfGuard, DEFAULT_CORRELATION_HEADER, DatabaseModule, type DatabaseModuleOptions, type FieldError, ForbiddenException, GoneException, type GuardConfig, HttpExceptionFilter, HttpLoggerInterceptor, type HttpLoggerOptions, HttpModule, InternalServerErrorException, type JwtConfig, LOGGER_MODULE_OPTIONS, type LogFormat, type LogLevel, type LogMetadata, LoggerModule, type LoggerModuleAsyncOptions, type LoggerModuleOptions, type LoggerOptionsFactory, LoggerService, MethodNotAllowedException, NotAcceptableException, NotFoundException, NotImplementedException, Onboarding, PayloadTooLargeException, PrimaryBaseRepository, PrimaryDatabaseService, type PrimaryDbConfig, type ProblemDetails, Public, type RegisteredSchema, RequestTimeoutException, ServiceUnavailableException, Tenant, TenantBaseRepository, TenantContextService, TenantDatabaseService, type TenantInfo, TooManyRequestsException, type TypedDrizzleClient, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, UserId, ValidationException, VrittiAuthGuard, addCorrelationIdToResponse, configureApiSdk, correlationStorage, defineConfig, generateCorrelationId, getConfig, getCorrelationContext, getHttpStatusTitle, getJwtExpiry, getRefreshCookieOptions, hashToken, resetConfig, runWithCorrelationContext, updateCorrelationContext, verifyTokenHash };
+export { type ApiErrorResponse, type ApiSdkConfig, AuthConfigModule, BadGatewayException, BadRequestException, ConflictException, type CookieConfig, type CorrelationContext, CorrelationIdMiddleware, DEFAULT_CORRELATION_HEADER, DatabaseModule, type DatabaseModuleOptions, type FieldError, ForbiddenException, GoneException, type GuardConfig, HttpExceptionFilter, HttpLoggerInterceptor, type HttpLoggerOptions, HttpProblemException, InternalServerErrorException, type JwtConfig, LOGGER_MODULE_OPTIONS, type LogFormat, type LogLevel, type LogMetadata, LoggerModule, type LoggerModuleAsyncOptions, type LoggerModuleOptions, type LoggerOptionsFactory, LoggerService, MethodNotAllowedException, NotAcceptableException, NotFoundException, NotImplementedException, Onboarding, PayloadTooLargeException, PrimaryBaseRepository, PrimaryDatabaseService, type PrimaryDbConfig, type ProblemDetails, type ProblemOptions, Public, type RegisteredSchema, RequestTimeoutException, SKIP_CSRF_KEY, ServiceUnavailableException, SkipCsrf, SseAuthGuard, Tenant, TenantBaseRepository, TenantContextService, TenantDatabaseService, type TenantInfo, TooManyRequestsException, type TypedDrizzleClient, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, UserId, ValidationException, VrittiAuthGuard, addCorrelationIdToResponse, configureApiSdk, correlationStorage, defineConfig, extractCountryFromPhone, generateCorrelationId, getConfig, getCorrelationContext, getHttpStatusTitle, getJwtExpiry, getRefreshCookieOptions, hashToken, normalizePhoneNumber, resetConfig, runWithCorrelationContext, updateCorrelationContext, verifyTokenHash };