mulguard 1.1.1 → 1.1.3

package/dist/core/types/auth.d.ts

@@ -1,15 +1,37 @@
 import { AuthErrorCode } from './errors';
+/**
+ * User interface representing an authenticated user.
+ *
+ * @property id - Unique user identifier
+ * @property email - User email address
+ * @property name - User display name
+ * @property avatar - Optional avatar URL
+ * @property roles - Optional user roles array
+ * @property emailVerified - Email verification status
+ *
+ * @example
+ * ```typescript
+ * const user: User = {
+ *   id: '123',
+ *   email: 'user@example.com',
+ *   name: 'John Doe',
+ *   emailVerified: true
+ * }
+ * ```
+ */
 export interface User {
-    id: string;
-    email: string;
-    name: string;
-    avatar?: string;
-    roles?: string[];
-    emailVerified?: boolean;
-    [key: string]: unknown;
+    readonly id: string;
+    readonly email: string;
+    readonly name: string;
+    readonly avatar?: string;
+    readonly roles?: readonly string[];
+    readonly emailVerified?: boolean;
+    readonly [key: string]: unknown;
 }
 /**
- * Session object containing user information and authentication tokens
+ * Session object containing user information and authentication tokens.
+ *
+ * @template TUser - User type (defaults to base User)
  *
  * @property user - User object with authentication information
  * @property expiresAt - Session expiration date/time
@@ -18,114 +40,251 @@ export interface User {
  * @property tokenType - Type of token (default: 'Bearer')
  * @property expiresIn - Token expiration time in seconds (optional)
  * @property refreshTokenExpiresAt - Refresh token expiration date/time (optional)
+ *
+ * @example
+ * ```typescript
+ * const session: Session = {
+ *   user: { id: '123', email: 'user@example.com', name: 'John' },
+ *   expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
+ *   accessToken: 'token123',
+ *   tokenType: 'Bearer'
+ * }
+ * ```
  */
-export interface Session {
-    user: User;
-    expiresAt: Date | string;
-    /** Access token for API authentication (optional) */
-    accessToken?: string;
-    /** Refresh token for token refresh (optional) */
-    refreshToken?: string;
-    /** Type of token (default: 'Bearer') */
-    tokenType?: 'Bearer' | 'Basic';
-    /** Token expiration time in seconds (optional) */
-    expiresIn?: number;
-    /** Refresh token expiration date/time (optional) */
-    refreshTokenExpiresAt?: Date | string;
-    [key: string]: unknown;
+export interface Session<TUser extends User = User> {
+    readonly user: TUser;
+    readonly expiresAt: Date | string;
+    readonly accessToken?: string;
+    readonly refreshToken?: string;
+    readonly tokenType?: 'Bearer' | 'Basic';
+    readonly expiresIn?: number;
+    readonly refreshTokenExpiresAt?: Date | string;
+    readonly [key: string]: unknown;
 }
 /**
- * Authentication result returned by sign-in, sign-up, and other auth actions
+ * Base authentication result type.
+ *
+ * @template TUser - User type (defaults to base User)
+ * @template TSession - Session type (defaults to base Session)
  *
  * @property success - Whether the authentication was successful
  * @property user - User object if authentication succeeded
  * @property session - Session object if authentication succeeded
  * @property error - Error message if authentication failed
  * @property errorCode - Specific error code for programmatic error handling
- * @property requires2FA - Whether 2FA verification is required (true when 2FA is needed)
+ * @property requires2FA - Whether 2FA verification is required
  * @property email - Email address (required when requires2FA is true)
  * @property userId - User ID (required when requires2FA is true)
  *
  * @example
  * ```typescript
- * const result = await auth.signIn.email({ email: 'user@example.com', password: 'password' })
+ * const result = await auth.signIn.email(credentials)
  * if (result.success) {
- *   // Authentication successful
- *   console.log('User:', result.user)
+ *   // TypeScript knows result.user and result.session exist
+ *   console.log(result.user.email)
  * } else if (result.requires2FA) {
- *   // 2FA required
- *   console.log('2FA required for:', result.email)
- * } else {
- *   // Authentication failed
- *   console.error('Error:', result.error, result.errorCode)
+ *   // TypeScript knows result.email and result.userId exist
+ *   await auth.verify2FA({ email: result.email, userId: result.userId, code: '123456' })
  * }
  * ```
  */
-export interface AuthResult {
-    success: boolean;
-    user?: User;
-    session?: Session;
-    error?: string;
-    /** Error code for programmatic error handling */
-    errorCode?: AuthErrorCode;
-    /** Indicates if 2FA is required */
-    requires2FA?: boolean;
-    /** Email for 2FA flow */
-    email?: string;
-    /** User ID for 2FA flow */
-    userId?: string;
+export interface AuthResult<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> {
+    readonly success: boolean;
+    readonly user?: TUser;
+    readonly session?: TSession;
+    readonly error?: string;
+    readonly errorCode?: AuthErrorCode;
+    readonly requires2FA?: boolean;
+    readonly email?: string;
+    readonly userId?: string;
 }
 /**
- * Two-factor authentication result
+ * Successful authentication result type.
+ *
+ * @template TUser - User type
+ * @template TSession - Session type
+ */
+export type SuccessfulAuthResult<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> = AuthResult<TUser, TSession> & {
+    readonly success: true;
+    readonly user: TUser;
+    readonly session: TSession;
+};
+/**
+ * Failed authentication result type.
+ *
+ * @template TUser - User type
+ * @template TSession - Session type
+ */
+export type FailedAuthResult<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> = AuthResult<TUser, TSession> & {
+    readonly success: false;
+    readonly error: string;
+};
+/**
+ * Two-factor authentication required result type.
  *
  * This type is returned when 2FA verification is required after initial authentication.
- * Use the `isTwoFactorRequired()` helper function to check if a result is of this type.
+ * Use the `isTwoFactorRequired()` type guard to narrow to this type.
+ *
+ * @template TUser - User type
+ * @template TSession - Session type
  *
- * @property success - Always false for 2FA required results
+ * @property success - Always false
  * @property requires2FA - Always true
  * @property email - Email address of the user requiring 2FA
  * @property userId - User ID requiring 2FA
  * @property errorCode - Always AuthErrorCode.TWO_FA_REQUIRED
- * @property twoFactorMethod - Method of 2FA (totp, sms, email) - optional
- * @property challengeToken - Challenge token for 2FA verification - optional
+ * @property twoFactorMethod - Method of 2FA (optional)
+ * @property challengeToken - Challenge token for 2FA verification (optional)
  *
  * @example
  * ```typescript
- * const result = await auth.signIn.email({ email: 'user@example.com', password: 'password' })
+ * const result = await auth.signIn.email(credentials)
  * if (isTwoFactorRequired(result)) {
  *   // TypeScript knows result is TwoFactorAuthResult here
  *   console.log('2FA required for:', result.email)
- *   console.log('Method:', result.twoFactorMethod) // 'totp' | 'sms' | 'email'
+ *   console.log('Method:', result.twoFactorMethod)
  * }
  * ```
  */
-export interface TwoFactorAuthResult extends AuthResult {
-    success: false;
-    requires2FA: true;
-    email: string;
-    userId: string;
-    error: '2FA_REQUIRED';
-    errorCode: AuthErrorCode.TWO_FA_REQUIRED;
-    /** Method of 2FA (totp, sms, email) - optional */
-    twoFactorMethod?: 'totp' | 'sms' | 'email';
-    /** Challenge token for 2FA verification - optional */
-    challengeToken?: string;
+export interface TwoFactorAuthResult<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> extends AuthResult<TUser, TSession> {
+    readonly success: false;
+    readonly requires2FA: true;
+    readonly email: string;
+    readonly userId: string;
+    readonly error: '2FA_REQUIRED';
+    readonly errorCode: AuthErrorCode.TWO_FA_REQUIRED;
+    readonly twoFactorMethod?: 'totp' | 'sms' | 'email';
+    readonly challengeToken?: string;
 }
 /**
- * Data for 2FA verification
+ * Email and password credentials for authentication.
+ *
+ * @property email - User email address
+ * @property password - User password
  */
-export interface Verify2FAData {
-    email: string;
-    userId: string;
-    code: string;
-}
 export interface EmailCredentials {
-    email: string;
-    password: string;
+    readonly email: string;
+    readonly password: string;
 }
+/**
+ * User registration data.
+ *
+ * @property email - User email address
+ * @property password - User password
+ * @property name - User display name
+ */
 export interface RegisterData {
-    email: string;
-    password: string;
-    name: string;
-    [key: string]: unknown;
+    readonly email: string;
+    readonly password: string;
+    readonly name: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * Data required for 2FA verification.
+ *
+ * @property email - User email address
+ * @property userId - User ID
+ * @property code - 2FA verification code
+ */
+export interface Verify2FAData {
+    readonly email: string;
+    readonly userId: string;
+    readonly code: string;
 }
+/**
+ * Type predicate to check if AuthResult indicates success.
+ *
+ * @template TUser - User type
+ * @template TSession - Session type
+ * @param result - AuthResult to check
+ * @returns True if result is successful
+ *
+ * @example
+ * ```typescript
+ * const result = await auth.signIn.email(credentials)
+ * if (isAuthSuccess(result)) {
+ *   // TypeScript narrows to SuccessfulAuthResult
+ *   console.log(result.user.email) // ✅ Type-safe
+ *   console.log(result.session.expiresAt) // ✅ Type-safe
+ * }
+ * ```
+ */
+export declare function isAuthSuccess<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(result: AuthResult<TUser, TSession>): result is SuccessfulAuthResult<TUser, TSession>;
+/**
+ * Type predicate to check if AuthResult indicates failure.
+ *
+ * @template TUser - User type
+ * @template TSession - Session type
+ * @param result - AuthResult to check
+ * @returns True if result indicates failure
+ *
+ * @example
+ * ```typescript
+ * const result = await auth.signIn.email(credentials)
+ * if (isAuthFailure(result)) {
+ *   // TypeScript narrows to FailedAuthResult
+ *   console.error(result.error) // ✅ Type-safe
+ * }
+ * ```
+ */
+export declare function isAuthFailure<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(result: AuthResult<TUser, TSession>): result is FailedAuthResult<TUser, TSession>;
+/**
+ * Type predicate to check if AuthResult indicates 2FA is required.
+ *
+ * @template TUser - User type
+ * @template TSession - Session type
+ * @param result - AuthResult to check
+ * @returns True if 2FA is required
+ *
+ * @example
+ * ```typescript
+ * const result = await auth.signIn.email(credentials)
+ * if (isTwoFactorRequired(result)) {
+ *   // TypeScript narrows to TwoFactorAuthResult
+ *   await auth.verify2FA({
+ *     email: result.email, // ✅ Type-safe
+ *     userId: result.userId, // ✅ Type-safe
+ *     code: '123456'
+ *   })
+ * }
+ * ```
+ */
+export declare function isTwoFactorRequired<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(result: AuthResult<TUser, TSession>): result is TwoFactorAuthResult<TUser, TSession>;
+/**
+ * TODO: Performance
+ * - [ ] Consider using branded types for User.id to prevent ID mixing
+ * - [ ] Add type-level optimizations for discriminated unions
+ * - [ ] Implement compile-time validation for email format
+ * - [ ] Add type-level session expiration checking
+ *
+ * TODO: Features
+ * - [ ] Add conditional types for provider-specific result variants
+ * - [ ] Implement type-safe error handling with exhaustiveness checking
+ * - [ ] Create type-level validation for credentials strength
+ * - [ ] Add generic constraints for custom User/Session extensions
+ * - [ ] Implement type-safe middleware chain types
+ *
+ * TODO: Type Safety
+ * - [ ] Add branded types for sensitive data (tokens, passwords)
+ * - [ ] Create type guards for all public interfaces
+ * - [ ] Add type-level validation for registration data
+ * - [ ] Implement type-safe error codes with const assertions
+ *
+ * TODO: Testing
+ * - [ ] Add type-level tests using ts-expect
+ * - [ ] Test type inference in various scenarios
+ * - [ ] Verify type narrowing with type predicates
+ * - [ ] Test generic constraints and conditional types
+ * - [ ] Add tests for discriminated union narrowing
+ *
+ * TODO: Documentation
+ * - [ ] Add more JSDoc examples for generic types
+ * - [ ] Document type-level patterns and best practices
+ * - [ ] Create migration guide for custom User/Session types
+ *
+ * TODO: Limitations
+ * - [ ] Type inference may be limited with very deep generic chains
+ * - [ ] Branded types add minimal runtime overhead
+ * - [ ] Deep readonly types may impact performance with large objects
+ * - [ ] Discriminated unions require explicit type guards for narrowing
+ */

package/dist/core/types/errors.d.ts

@@ -1,44 +1,200 @@
 /**
- * Authentication error codes
+ * Authentication error codes and error handling types.
+ *
+ * @module @mulguard/core/types/errors
+ */
+/**
+ * Authentication error code enumeration.
+ *
+ * Provides specific error codes for programmatic error handling.
+ *
+ * @example
+ * ```typescript
+ * if (result.errorCode === AuthErrorCode.INVALID_CREDENTIALS) {
+ *   // Handle invalid credentials
+ * } else if (result.errorCode === AuthErrorCode.TWO_FA_REQUIRED) {
+ *   // Handle 2FA requirement
+ * }
+ * ```
  */
 export declare enum AuthErrorCode {
-    /** Invalid email or password */
+    /** Invalid email or password credentials */
     INVALID_CREDENTIALS = "INVALID_CREDENTIALS",
-    /** Account is temporarily locked */
+    /** Account is temporarily locked due to failed attempts */
     ACCOUNT_LOCKED = "ACCOUNT_LOCKED",
     /** Account is inactive or disabled */
     ACCOUNT_INACTIVE = "ACCOUNT_INACTIVE",
-    /** Two-factor authentication required */
+    /** Two-factor authentication is required */
     TWO_FA_REQUIRED = "TWO_FA_REQUIRED",
     /** Invalid two-factor authentication code */
     INVALID_TWO_FA_CODE = "INVALID_TWO_FA_CODE",
     /** Session has expired */
     SESSION_EXPIRED = "SESSION_EXPIRED",
-    /** User is not authorized */
+    /** User is not authorized for this operation */
     UNAUTHORIZED = "UNAUTHORIZED",
-    /** Network or API error */
+    /** Network or API communication error */
     NETWORK_ERROR = "NETWORK_ERROR",
-    /** Validation error */
+    /** Input validation error */
     VALIDATION_ERROR = "VALIDATION_ERROR",
     /** Rate limit exceeded */
     RATE_LIMITED = "RATE_LIMITED",
-    /** Unknown error */
+    /** Unknown or unexpected error */
     UNKNOWN_ERROR = "UNKNOWN_ERROR"
 }
 /**
- * Authentication error interface
+ * Authentication error interface.
+ *
+ * Provides structured error information with code, message, and optional metadata.
+ *
+ * @property code - Specific error code
+ * @property message - Human-readable error message
+ * @property statusCode - HTTP status code (if applicable)
+ * @property details - Additional error details (optional)
+ *
+ * @example
+ * ```typescript
+ * const error: AuthError = {
+ *   code: AuthErrorCode.INVALID_CREDENTIALS,
+ *   message: 'Invalid email or password',
+ *   statusCode: 401
+ * }
+ * ```
  */
 export interface AuthError {
-    /** Error code */
-    code: AuthErrorCode;
-    /** Human-readable error message */
-    message: string;
-    /** HTTP status code (if applicable) */
-    statusCode?: number;
-    /** Additional error details */
-    details?: unknown;
+    readonly code: AuthErrorCode;
+    readonly message: string;
+    readonly statusCode?: number;
+    readonly details?: unknown;
 }
 /**
- * Create an authentication error
+ * Error result type for failed operations.
+ *
+ * @template TCode - Error code type (defaults to AuthErrorCode)
+ */
+export type ErrorResult<TCode extends AuthErrorCode = AuthErrorCode> = {
+    readonly success: false;
+    readonly error: string;
+    readonly errorCode: TCode;
+    readonly details?: unknown;
+};
+/**
+ * Creates an authentication error object.
+ *
+ * @param code - Error code
+ * @param message - Human-readable error message
+ * @param statusCode - HTTP status code (optional)
+ * @param details - Additional error details (optional)
+ * @returns AuthError object
+ *
+ * @example
+ * ```typescript
+ * const error = createAuthError(
+ *   AuthErrorCode.INVALID_CREDENTIALS,
+ *   'Invalid email or password',
+ *   401
+ * )
+ * ```
  */
 export declare function createAuthError(code: AuthErrorCode, message: string, statusCode?: number, details?: unknown): AuthError;
+/**
+ * Creates an error result for failed authentication operations.
+ *
+ * @template TCode - Error code type
+ * @param code - Error code
+ * @param message - Error message
+ * @param details - Additional error details (optional)
+ * @returns ErrorResult object
+ *
+ * @example
+ * ```typescript
+ * const result = createErrorResult(
+ *   AuthErrorCode.INVALID_CREDENTIALS,
+ *   'Invalid email or password'
+ * )
+ * ```
+ */
+export declare function createErrorResult<TCode extends AuthErrorCode = AuthErrorCode>(code: TCode, message: string, details?: unknown): ErrorResult<TCode>;
+/**
+ * HTTP status code mapping for error codes.
+ *
+ * Maps authentication error codes to appropriate HTTP status codes.
+ */
+export declare const ERROR_STATUS_MAP: Readonly<Record<AuthErrorCode, number>>;
+/**
+ * Gets the HTTP status code for an error code.
+ *
+ * @param code - Error code
+ * @returns HTTP status code
+ *
+ * @example
+ * ```typescript
+ * const statusCode = getErrorStatusCode(AuthErrorCode.INVALID_CREDENTIALS)
+ * // Returns 401
+ * ```
+ */
+export declare function getErrorStatusCode(code: AuthErrorCode): number;
+/**
+ * Type predicate to check if a value is an AuthError.
+ *
+ * @param value - Value to check
+ * @returns True if value is an AuthError
+ *
+ * @example
+ * ```typescript
+ * if (isAuthError(error)) {
+ *   // TypeScript knows error is AuthError here
+ *   console.log(error.code, error.message)
+ * }
+ * ```
+ */
+export declare function isAuthError(value: unknown): value is AuthError;
+/**
+ * Type predicate to check if a value is an ErrorResult.
+ *
+ * @param value - Value to check
+ * @returns True if value is an ErrorResult
+ *
+ * @example
+ * ```typescript
+ * if (isErrorResult(result)) {
+ *   // TypeScript knows result is ErrorResult here
+ *   console.log(result.errorCode, result.error)
+ * }
+ * ```
+ */
+export declare function isErrorResult(value: unknown): value is ErrorResult;
+/**
+ * TODO: Performance
+ * - [ ] Consider using const assertions for error code strings
+ * - [ ] Add type-level validation for error code mappings
+ * - [ ] Implement compile-time error code exhaustiveness checking
+ *
+ * TODO: Features
+ * - [ ] Add error recovery strategies
+ * - [ ] Implement error code hierarchies/categories
+ * - [ ] Add localized error messages support
+ * - [ ] Create error code to user-friendly message mapping
+ * - [ ] Add error code metadata (retryable, transient, etc.)
+ *
+ * TODO: Type Safety
+ * - [ ] Add branded types for error codes
+ * - [ ] Implement type-safe error code unions
+ * - [ ] Add exhaustiveness checking for error handling
+ * - [ ] Create type-safe error code validation
+ *
+ * TODO: Testing
+ * - [ ] Add tests for error code mappings
+ * - [ ] Test type guards with various inputs
+ * - [ ] Verify error result type narrowing
+ * - [ ] Test error factory functions
+ *
+ * TODO: Documentation
+ * - [ ] Add examples for each error code
+ * - [ ] Document error handling best practices
+ * - [ ] Create error code reference guide
+ *
+ * TODO: Limitations
+ * - [ ] Error code enum may need extension for custom errors
+ * - [ ] Status code mapping is fixed (consider configurable)
+ * - [ ] Error details type is unknown (consider generic)
+ */