@vritti/api-sdk 0.0.6 → 0.0.8

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _nestjs_common from '@nestjs/common';
-import { DynamicModule, OnModuleDestroy, OnModuleInit, Logger, CanActivate, ExecutionContext, ExceptionFilter, ArgumentsHost } from '@nestjs/common';
+import { DynamicModule, OnModuleDestroy, OnModuleInit, Logger, CanActivate, ExecutionContext, ExceptionFilter, ArgumentsHost, HttpException, HttpStatus } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { Reflector } from '@nestjs/core';
 import { JwtService } from '@nestjs/jwt';
@@ -1300,29 +1300,468 @@ declare class CsrfGuard implements CanActivate {
 }
 
 /**
- * Global HTTP Exception Filter
+ * Converts an HTTP status code to its corresponding title string.
+ * Uses the HttpStatus enum to map status codes to human-readable titles.
  *
- * Standardizes all error responses in the format:
+ * @param status - The HTTP status code
+ * @returns The human-readable title for the status code
+ *
+ * @example
+ * getHttpStatusTitle(400) // Returns: "Bad Request"
+ * getHttpStatusTitle(404) // Returns: "Not Found"
+ * getHttpStatusTitle(500) // Returns: "Internal Server Error"
+ */
+declare function getHttpStatusTitle(status: number): string;
+/**
+ * Global HTTP Exception Filter implementing RFC 7807 Problem Details
+ *
+ * Transforms all exceptions into a standardized RFC 7807 format:
  * {
- *   errors: [{ field: string, message: string }],
- *   message?: string,
- *   statusCode: number,
- *   timestamp: string,
- *   path: string
+ *   title: string,        // Human-readable status title
+ *   status: number,       // HTTP status code
+ *   detail: string,       // Detailed error description
+ *   errors: FieldError[]  // Field-specific error messages
  * }
  *
  * Handles:
- * - Validation errors (class-validator) - Converts to field-specific errors
- * - HTTP exceptions - Maps to standardized format
- * - Unknown errors - Returns generic 500 error
+ * - Custom field exceptions from @vritti/api-sdk (BaseFieldException)
+ * - Class-validator DTO validation errors
+ * - Standard NestJS HTTP exceptions
+ * - Unknown errors
  */
 declare class HttpExceptionFilter implements ExceptionFilter {
     private readonly logger;
     catch(exception: unknown, host: ArgumentsHost): void;
-    /**
-     * Parse class-validator error messages into field-specific errors
-     */
-    private parseValidationErrors;
 }
 
-export { AuthConfigModule, CsrfGuard, DatabaseModule, type DatabaseModuleOptions, HttpExceptionFilter, HttpModule, Onboarding, PrimaryBaseRepository, PrimaryDatabaseService, type PrimaryDbConfig, Public, Tenant, TenantBaseRepository, TenantContextService, TenantDatabaseService, type TenantInfo, VrittiAuthGuard };
+interface FieldError$1 {
+    field?: string;
+    message: string;
+}
+interface ProblemDetails {
+    title: string;
+    status: number;
+    detail: string;
+}
+interface ApiErrorResponse extends ProblemDetails {
+    errors: FieldError$1[];
+}
+
+interface FieldError {
+    field?: string;
+    message: string;
+}
+declare abstract class BaseFieldException extends HttpException {
+    constructor(statusOrMessageOrErrors: HttpStatus | string | FieldError[], messageOrStatus?: string | HttpStatus, statusOrDetail?: HttpStatus | string, detail?: string);
+}
+
+/**
+ * Exception thrown when a request is malformed or contains invalid data (HTTP 400).
+ *
+ * @example
+ * // 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');
+ *
+ * // Multiple field errors
+ * throw new BadRequestException([
+ *   { field: 'email', message: 'Invalid email' },
+ *   { field: 'password', message: 'Password too short' }
+ * ]);
+ */
+declare class BadRequestException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+/**
+ * Exception thrown when authentication is required or has failed (HTTP 401).
+ *
+ * @example
+ * // 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' }
+ * ]);
+ */
+declare class UnauthorizedException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+/**
+ * Exception thrown when the user does not have permission to access a resource (HTTP 403).
+ *
+ * @example
+ * // Simple 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');
+ *
+ * // Multiple field errors
+ * throw new ForbiddenException([
+ *   { field: 'action', message: 'Insufficient permissions' }
+ * ]);
+ */
+declare class ForbiddenException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+/**
+ * Exception thrown when a requested resource cannot be found (HTTP 404).
+ *
+ * @example
+ * // 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');
+ *
+ * // Multiple field errors
+ * throw new NotFoundException([
+ *   { field: 'userId', message: 'User does not exist' }
+ * ]);
+ */
+declare class NotFoundException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+/**
+ * Exception thrown when a request conflicts with the current state (HTTP 409).
+ * Commonly used for duplicate resources or concurrent modification issues.
+ *
+ * @example
+ * // Simple message
+ * throw new ConflictException('Resource already exists');
+ *
+ * // Field-specific error
+ * throw new ConflictException('email', 'Email already registered');
+ *
+ * // With detail
+ * throw new ConflictException('email', 'Email already exists', 'Try logging in instead');
+ *
+ * // Multiple field errors
+ * throw new ConflictException([
+ *   { field: 'email', message: 'Email already in use' }
+ * ]);
+ */
+declare class ConflictException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+/**
+ * Exception thrown when an unexpected server error occurs (HTTP 500).
+ *
+ * @example
+ * // 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' }
+ * ]);
+ */
+declare class InternalServerErrorException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+/**
+ * Exception thrown when request validation fails (HTTP 400).
+ * 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' }
+ * ]);
+ *
+ * // With detail
+ * throw new ValidationException(
+ *   [{ field: 'email', message: 'Invalid format' }],
+ *   'Please correct the errors and try again'
+ * );
+ */
+declare class ValidationException extends BaseFieldException {
+    constructor(errors: FieldError[], detail?: string);
+}
+
+/**
+ * Exception thrown when the request is well-formed but contains semantic errors (HTTP 422).
+ * Used for business logic validation failures that prevent processing.
+ *
+ * @example
+ * // 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');
+ *
+ * // 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' }
+ * ]);
+ */
+declare class UnprocessableEntityException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+/**
+ * Exception thrown when rate limiting is triggered (HTTP 429).
+ * Used to prevent abuse and ensure fair resource usage.
+ *
+ * @example
+ * // Simple message
+ * throw new TooManyRequestsException('Too many requests');
+ *
+ * // Field-specific error
+ * throw new TooManyRequestsException('api', 'Rate limit exceeded');
+ *
+ * // With detail
+ * throw new TooManyRequestsException('api', 'Rate limit exceeded', 'Try again in 60 seconds');
+ *
+ * // Multiple field errors
+ * throw new TooManyRequestsException([
+ *   { field: 'requests', message: 'Rate limit exceeded for this endpoint' }
+ * ]);
+ */
+declare class TooManyRequestsException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+/**
+ * Exception thrown when the service is temporarily unavailable (HTTP 503).
+ * Used during maintenance, overload, or temporary outages.
+ *
+ * @example
+ * // 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');
+ *
+ * // Multiple field errors
+ * throw new ServiceUnavailableException([
+ *   { field: 'database', message: 'Database is temporarily unavailable' }
+ * ]);
+ */
+declare class ServiceUnavailableException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+/**
+ * Exception thrown when an HTTP method is not supported for the endpoint (HTTP 405).
+ * For example, when a POST is sent to a GET-only endpoint.
+ *
+ * @example
+ * // 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');
+ *
+ * // Multiple field errors
+ * throw new MethodNotAllowedException([
+ *   { field: 'method', message: 'DELETE is not allowed on this resource' }
+ * ]);
+ */
+declare class MethodNotAllowedException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+/**
+ * Exception thrown when a resource has been permanently removed (HTTP 410).
+ * Unlike 404, this indicates the resource existed but is intentionally gone.
+ *
+ * @example
+ * // 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');
+ *
+ * // Multiple field errors
+ * throw new GoneException([
+ *   { field: 'resource', message: 'This content has been permanently removed' }
+ * ]);
+ */
+declare class GoneException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+/**
+ * Exception thrown when content negotiation fails (HTTP 406).
+ * Used when the server cannot produce a response matching the Accept headers.
+ *
+ * @example
+ * // Simple message
+ * throw new NotAcceptableException('Requested format not available');
+ *
+ * // Field-specific error
+ * throw new NotAcceptableException('accept', 'Cannot produce response in requested format');
+ *
+ * // With detail
+ * throw new NotAcceptableException('accept', 'Format not supported', 'Only JSON is available');
+ *
+ * // Multiple field errors
+ * throw new NotAcceptableException([
+ *   { field: 'contentType', message: 'XML format is not supported' }
+ * ]);
+ */
+declare class NotAcceptableException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+/**
+ * Exception thrown when a request takes too long to process (HTTP 408).
+ * Used when the client or server times out while waiting for completion.
+ *
+ * @example
+ * // 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');
+ *
+ * // Multiple field errors
+ * throw new RequestTimeoutException([
+ *   { field: 'processing', message: 'Request took too long to complete' }
+ * ]);
+ */
+declare class RequestTimeoutException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+/**
+ * Exception thrown when request payload exceeds size limits (HTTP 413).
+ * Commonly used for file upload size restrictions or large request bodies.
+ *
+ * @example
+ * // 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');
+ *
+ * // Multiple field errors
+ * throw new PayloadTooLargeException([
+ *   { field: 'upload', message: 'File exceeds 10MB limit' }
+ * ]);
+ */
+declare class PayloadTooLargeException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+/**
+ * Exception thrown when the media type of the request is not supported (HTTP 415).
+ * Used when the Content-Type header specifies an unsupported format.
+ *
+ * @example
+ * // 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');
+ *
+ * // Multiple field errors
+ * throw new UnsupportedMediaTypeException([
+ *   { field: 'contentType', message: 'application/xml is not supported' }
+ * ]);
+ */
+declare class UnsupportedMediaTypeException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+/**
+ * Exception thrown when a feature or endpoint is not yet implemented (HTTP 501).
+ * Used for planned but unavailable functionality.
+ *
+ * @example
+ * // 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' }
+ * ]);
+ */
+declare class NotImplementedException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+/**
+ * Exception thrown when a gateway or proxy receives an invalid response (HTTP 502).
+ * Used when a server acting as a gateway gets an error from an upstream server.
+ *
+ * @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');
+ *
+ * // Multiple field errors
+ * throw new BadGatewayException([
+ *   { field: 'gateway', message: 'Invalid response from upstream server' }
+ * ]);
+ */
+declare class BadGatewayException extends BaseFieldException {
+    constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
+}
+
+export { type ApiErrorResponse, AuthConfigModule, BadGatewayException, BadRequestException, BaseFieldException, ConflictException, CsrfGuard, DatabaseModule, type DatabaseModuleOptions, type FieldError, ForbiddenException, GoneException, HttpExceptionFilter, HttpModule, InternalServerErrorException, MethodNotAllowedException, NotAcceptableException, NotFoundException, NotImplementedException, Onboarding, PayloadTooLargeException, PrimaryBaseRepository, PrimaryDatabaseService, type PrimaryDbConfig, type ProblemDetails, Public, RequestTimeoutException, ServiceUnavailableException, Tenant, TenantBaseRepository, TenantContextService, TenantDatabaseService, type TenantInfo, TooManyRequestsException, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, ValidationException, VrittiAuthGuard, getHttpStatusTitle };