@vritti/api-sdk 0.1.5 → 0.1.7

package/dist/index.d.cts

@@ -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;
 }
 
 /**
@@ -582,6 +628,12 @@ interface CookieConfig {
      * @default 'strict'
      */
     refreshCookieSameSite: 'strict' | 'lax' | 'none';
+    /**
+     * Cookie domain (e.g., 'localhost' for dev, '.vritti.cloud' for prod)
+     * Required for cross-subdomain auth (e.g., cloud.localhost accessing localhost API)
+     * @default undefined (uses request domain)
+     */
+    refreshCookieDomain?: string;
 }
 /**
  * JWT token configuration options
@@ -674,13 +726,7 @@ declare function resetConfig(): void;
 /**
  * Get refresh cookie options (convenience method)
  */
-declare function getRefreshCookieOptions(): {
-    httpOnly: boolean;
-    secure: boolean;
-    sameSite: "strict" | "lax" | "none";
-    path: string;
-    maxAge: number;
-};
+declare function getRefreshCookieOptions(): Record<string, unknown>;
 /**
  * Get JWT expiry settings (convenience method)
  */
@@ -2075,30 +2121,25 @@ declare class HttpExceptionFilter implements ExceptionFilter {
     catch(exception: unknown, host: ArgumentsHost): void;
 }
 
+declare const SKIP_CSRF_KEY = "skipCsrf";
 /**
- * CSRF Guard
+ * 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.
  *
- * 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
- *
- * 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
@@ -2114,6 +2155,19 @@ declare class CsrfGuard implements CanActivate {
 declare class HttpModule {
 }
 
+/**
+ * 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 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 +2569,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, BaseFieldException, ConflictException, type CookieConfig, type CorrelationContext, CorrelationIdMiddleware, 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, 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 };

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;
 }
 
 /**
@@ -582,6 +628,12 @@ interface CookieConfig {
      * @default 'strict'
      */
     refreshCookieSameSite: 'strict' | 'lax' | 'none';
+    /**
+     * Cookie domain (e.g., 'localhost' for dev, '.vritti.cloud' for prod)
+     * Required for cross-subdomain auth (e.g., cloud.localhost accessing localhost API)
+     * @default undefined (uses request domain)
+     */
+    refreshCookieDomain?: string;
 }
 /**
  * JWT token configuration options
@@ -674,13 +726,7 @@ declare function resetConfig(): void;
 /**
  * Get refresh cookie options (convenience method)
  */
-declare function getRefreshCookieOptions(): {
-    httpOnly: boolean;
-    secure: boolean;
-    sameSite: "strict" | "lax" | "none";
-    path: string;
-    maxAge: number;
-};
+declare function getRefreshCookieOptions(): Record<string, unknown>;
 /**
  * Get JWT expiry settings (convenience method)
  */
@@ -2075,30 +2121,25 @@ declare class HttpExceptionFilter implements ExceptionFilter {
     catch(exception: unknown, host: ArgumentsHost): void;
 }
 
+declare const SKIP_CSRF_KEY = "skipCsrf";
 /**
- * CSRF Guard
+ * 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.
  *
- * 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
- *
- * 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
@@ -2114,6 +2155,19 @@ declare class CsrfGuard implements CanActivate {
 declare class HttpModule {
 }
 
+/**
+ * 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 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 +2569,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, BaseFieldException, ConflictException, type CookieConfig, type CorrelationContext, CorrelationIdMiddleware, 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, 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 };