/**
 * Interview Token Types
 *
 * Type definitions for the interview scheduling token system.
 * Includes JWT payload structure, validation results, and database models.
 *
 * @module lib/types/interview-token.types
 */

/**
 * JWT Token Payload Structure
 */
export interface InterviewTokenPayload {
  /** UUID of the job application */
  applicationId: string;

  /** UUID of the job */
  jobId: string;

  /** Email of the applicant */
  applicantEmail: string;

  /** Issued at timestamp (seconds since epoch) */
  iat: number;

  /** Expiration timestamp (seconds since epoch) */
  exp: number;

  /** JWT ID (unique token identifier) */
  jti: string;
}

/**
 * Token Generation Configuration
 */
export interface TokenGenerationConfig {
  /** Application ID */
  applicationId: string;

  /** Job ID */
  jobId: string;

  /** Applicant email */
  applicantEmail: string;

  /** Optional custom expiry (defaults to 72 hours) */
  expiryHours?: number;
}

/**
 * Token Validation Result
 */
export interface TokenValidationResult {
  /** Whether token is valid */
  valid: boolean;

  /** Token payload if valid */
  payload?: InterviewTokenPayload;

  /** Database token record if found */
  tokenRecord?: InterviewTokenRecord;

  /** Error message if invalid */
  error?: string;

  /** Error code for client handling */
  errorCode?: 'EXPIRED' | 'USED' | 'REVOKED' | 'INVALID' | 'NOT_FOUND';
}

/**
 * Token Generation Result
 */
export interface TokenGenerationResult {
  /** Whether generation succeeded */
  success: boolean;

  /** Generated JWT token */
  token?: string;

  /** Token ID (jti) */
  tokenId?: string;

  /** Expiration date */
  expiresAt?: Date;

  /** Error message if failed */
  error?: string;
}

/**
 * Database Token Record
 */
export interface InterviewTokenRecord {
  /** UUID primary key */
  id: string;

  /** JWT token string */
  token: string;

  /** Application ID */
  applicationId: string;

  /** Job ID */
  jobId: string;

  /** Applicant email */
  applicantEmail: string;

  /** Token expiration */
  expiresAt: Date;

  /** When token was used (null if unused) */
  usedAt: Date | null;

  /** Whether token is revoked */
  isRevoked: boolean;

  /** Creation timestamp */
  createdAt: Date;

  /** Update timestamp */
  updatedAt: Date;
}

/**
 * Token Details Result
 */
export interface TokenDetailsResult {
  /** Whether extraction succeeded */
  success: boolean;

  /** Application ID */
  applicationId?: string;

  /** Job ID */
  jobId?: string;

  /** Applicant email */
  applicantEmail?: string;

  /** Token ID */
  tokenId?: string;

  /** Expiration date */
  expiresAt?: Date;

  /** Issued at date */
  issuedAt?: Date;

  /** Error message if failed */
  error?: string;
}

/**
 * Token Configuration Constants
 */
export const TOKEN_CONFIG = {
  /** Token expiry in hours */
  EXPIRY_HOURS: 72,

  /** Token expiry in seconds (for JWT) */
  EXPIRY_SECONDS: 72 * 60 * 60, // 259200 seconds

  /** JWT algorithm */
  ALGORITHM: 'HS256' as const,

  /** Rate limit: tokens per hour per application */
  RATE_LIMIT_PER_HOUR: 3,

  /** Environment variable for secret key */
  SECRET_ENV_VAR: 'INTERVIEW_TOKEN_SECRET',
} as const;

/**
 * Token Service Interface
 */
export interface IInterviewTokenService {
  /**
   * Generate a new interview token
   */
  generateInterviewToken(config: TokenGenerationConfig): Promise<TokenGenerationResult>;

  /**
   * Validate a token
   */
  validateInterviewToken(token: string): Promise<TokenValidationResult>;

  /**
   * Mark token as used
   */
  markTokenAsUsed(tokenId: string): Promise<boolean>;

  /**
   * Revoke a token
   */
  revokeToken(tokenId: string): Promise<boolean>;

  /**
   * Get token details
   */
  getTokenDetails(token: string): Promise<TokenDetailsResult>;
}
