380 lines
8.4 KiB
TypeScript
380 lines
8.4 KiB
TypeScript
/**
|
|
* Domain type definitions for portfolio management.
|
|
*
|
|
* Provides comprehensive type safety for domain data, metrics, and UI components.
|
|
* All domain-related interfaces include renewal tracking, ownership metrics, and
|
|
* categorization for portfolio organization.
|
|
*
|
|
* @module lib/types/domain
|
|
* @category Types
|
|
*/
|
|
|
|
import type { ComponentType, Dispatch, SetStateAction } from 'react'
|
|
import type { IconType } from 'react-icons'
|
|
import type { LucideIcon } from 'lucide-react'
|
|
|
|
/**
|
|
* Domain status indicating current usage state.
|
|
*
|
|
* @remarks
|
|
* - `active`: Domain is actively being used for a website or service
|
|
* - `parked`: Domain is registered but not currently in use
|
|
* - `reserved`: Domain is reserved for future use
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const status: DomainStatus = 'active'
|
|
* ```
|
|
*
|
|
* @public
|
|
*/
|
|
export type DomainStatus = 'active' | 'parked' | 'reserved'
|
|
|
|
/**
|
|
* Domain category for portfolio organization.
|
|
*
|
|
* @remarks
|
|
* Categories help organize domains by purpose and importance:
|
|
* - `personal`: Personal branding or portfolio domains
|
|
* - `service`: Production services and applications
|
|
* - `project`: Project-specific or experimental domains
|
|
* - `fun`: Hobby or entertainment domains
|
|
* - `legacy`: Older domains maintained for historical reasons
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const category: DomainCategory = 'service'
|
|
* ```
|
|
*
|
|
* @public
|
|
*/
|
|
export type DomainCategory = 'personal' | 'service' | 'project' | 'fun' | 'legacy'
|
|
|
|
/**
|
|
* Supported domain registrar identifiers.
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const registrar: DomainRegistrarId = 'Namecheap'
|
|
* ```
|
|
*
|
|
* @public
|
|
*/
|
|
export type DomainRegistrarId = 'Spaceship' | 'Namecheap' | 'Name.com' | 'Dynadot'
|
|
|
|
/**
|
|
* Sort options for domain lists.
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const sortBy: DomainSortOption = 'expiration'
|
|
* ```
|
|
*
|
|
* @public
|
|
*/
|
|
export type DomainSortOption = 'name' | 'expiration' | 'ownership' | 'registrar'
|
|
|
|
/**
|
|
* Timeline event types for domain history.
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const eventType: DomainTimelineEventType = 'renewal'
|
|
* ```
|
|
*
|
|
* @public
|
|
*/
|
|
export type DomainTimelineEventType = 'registration' | 'renewal'
|
|
|
|
/**
|
|
* Domain renewal record tracking renewal history.
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const renewal: Renewal = {
|
|
* date: '2024-01-15',
|
|
* years: 2
|
|
* }
|
|
* ```
|
|
*
|
|
* @public
|
|
*/
|
|
export interface Renewal {
|
|
/** ISO date string of renewal (YYYY-MM-DD format) */
|
|
date: string
|
|
|
|
/** Number of years renewed */
|
|
years: number
|
|
}
|
|
|
|
/**
|
|
* Registrar configuration for UI display.
|
|
*
|
|
* @example
|
|
* ```tsx
|
|
* import { SiNamecheap } from 'react-icons/si'
|
|
*
|
|
* const config: RegistrarConfig = {
|
|
* name: 'Namecheap',
|
|
* icon: SiNamecheap,
|
|
* color: '#FF6C2C'
|
|
* }
|
|
* ```
|
|
*
|
|
* @public
|
|
*/
|
|
export interface RegistrarConfig {
|
|
/** Display name of the registrar */
|
|
name: string
|
|
|
|
/** Icon component (from react-icons or custom) */
|
|
icon: IconType | ComponentType<{className?: string}>
|
|
|
|
/** Brand color for visual identification */
|
|
color: string
|
|
}
|
|
|
|
/**
|
|
* Core domain data structure.
|
|
*
|
|
* Base interface containing all raw domain information without computed metrics.
|
|
* Use {@link DomainWithMetrics} for enriched data with ownership calculations.
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const domain: Domain = {
|
|
* domain: 'example.com',
|
|
* usage: 'Personal portfolio website',
|
|
* registrar: 'Namecheap',
|
|
* autoRenew: true,
|
|
* status: 'active',
|
|
* category: 'personal',
|
|
* tags: ['portfolio', 'web'],
|
|
* renewals: [
|
|
* { date: '2022-01-15', years: 1 },
|
|
* { date: '2023-01-15', years: 2 }
|
|
* ]
|
|
* }
|
|
* ```
|
|
*
|
|
* @public
|
|
*/
|
|
export interface Domain {
|
|
/** Domain name (e.g., 'example.com') */
|
|
domain: string
|
|
|
|
/** Description of domain usage/purpose */
|
|
usage: string
|
|
|
|
/** Registrar where domain is registered */
|
|
registrar: DomainRegistrarId
|
|
|
|
/** Whether auto-renewal is enabled */
|
|
autoRenew: boolean
|
|
|
|
/** Current status of the domain */
|
|
status: DomainStatus
|
|
|
|
/** Portfolio category for organization */
|
|
category: DomainCategory
|
|
|
|
/** Tags for filtering and search */
|
|
tags: string[]
|
|
|
|
/** Renewal history (chronological order) */
|
|
renewals: Renewal[]
|
|
}
|
|
|
|
/**
|
|
* Enriched domain data with computed ownership and expiration metrics.
|
|
*
|
|
* Extends {@link Domain} with calculated fields for ownership duration, expiration
|
|
* tracking, and renewal progress.
|
|
*
|
|
* @remarks
|
|
* All date calculations use UTC to ensure consistent timezone handling. The renewal
|
|
* progress percentage helps visualize time until next renewal is needed.
|
|
*
|
|
* This interface is generated by `DomainService.enrichDomain()` method.
|
|
* All domains returned by DomainService methods include these computed properties.
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* import { DomainService } from '@/lib/services'
|
|
*
|
|
* const enriched: DomainWithMetrics = DomainService.enrichDomain(domain)
|
|
* console.log(enriched.ownershipYears) // 2
|
|
* console.log(enriched.daysUntilExpiration) // 347
|
|
* console.log(enriched.isExpiringSoon) // false
|
|
* console.log(enriched.renewalProgressPercent) // 15.2
|
|
* console.log(enriched.tld) // 'com'
|
|
* ```
|
|
*
|
|
* @public
|
|
*/
|
|
export interface DomainWithMetrics extends Domain {
|
|
/** Calculated expiration date based on last renewal */
|
|
expirationDate: Date
|
|
|
|
/** First renewal date (registration date) */
|
|
registrationDate: Date
|
|
|
|
/** Total days of ownership */
|
|
ownershipDays: number
|
|
|
|
/** Full years of ownership (floored) */
|
|
ownershipYears: number
|
|
|
|
/** Remaining months after full years */
|
|
ownershipMonths: number
|
|
|
|
/** Days until domain expires */
|
|
daysUntilExpiration: number
|
|
|
|
/** Percentage of current renewal period completed (0-100) */
|
|
renewalProgressPercent: number
|
|
|
|
/** True if expiring within 90 days */
|
|
isExpiringSoon: boolean
|
|
|
|
/** Date of next scheduled renewal */
|
|
nextRenewalDate: Date
|
|
|
|
/** Top-level domain extension (e.g., 'com', 'net') */
|
|
tld: string
|
|
}
|
|
|
|
/**
|
|
* Visual styling configuration for domain status/category badges.
|
|
*
|
|
* @example
|
|
* ```tsx
|
|
* import { Circle } from 'lucide-react'
|
|
*
|
|
* const option: DomainVisualOption = {
|
|
* label: 'Active',
|
|
* icon: Circle,
|
|
* color: 'text-green-400',
|
|
* bg: 'bg-green-500/20',
|
|
* border: 'border-green-500/30'
|
|
* }
|
|
* ```
|
|
*
|
|
* @public
|
|
*/
|
|
export interface DomainVisualOption {
|
|
/** Display label text */
|
|
label: string
|
|
|
|
/** Lucide icon component */
|
|
icon: LucideIcon
|
|
|
|
/** Tailwind text color class */
|
|
color: string
|
|
|
|
/** Tailwind background color class */
|
|
bg: string
|
|
|
|
/** Tailwind border color class */
|
|
border: string
|
|
}
|
|
|
|
/**
|
|
* Complete visual configuration mapping for all domain statuses and categories.
|
|
*
|
|
* @public
|
|
*/
|
|
export type DomainVisualConfig = {
|
|
/** Visual options for each status type */
|
|
status: Record<DomainStatus, DomainVisualOption>
|
|
|
|
/** Visual options for each category type */
|
|
category: Record<DomainCategory, DomainVisualOption>
|
|
}
|
|
|
|
/**
|
|
* Mapping of registrar IDs to their configuration.
|
|
*
|
|
* @public
|
|
*/
|
|
export type DomainRegistrarMap = Record<DomainRegistrarId, RegistrarConfig>
|
|
|
|
/**
|
|
* Domain timeline event for renewal/registration history display.
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const event: DomainTimelineEvent = {
|
|
* date: new Date('2024-01-15'),
|
|
* type: 'renewal',
|
|
* years: 2
|
|
* }
|
|
* ```
|
|
*
|
|
* @public
|
|
*/
|
|
export interface DomainTimelineEvent {
|
|
/** Event date */
|
|
date: Date
|
|
|
|
/** Event type (registration or renewal) */
|
|
type: DomainTimelineEventType
|
|
|
|
/** Number of years for the renewal */
|
|
years: number
|
|
}
|
|
|
|
/**
|
|
* Props for DomainCard component.
|
|
*
|
|
* @public
|
|
*/
|
|
export interface DomainCardProps {
|
|
/** Domain data to display */
|
|
domain: Domain
|
|
}
|
|
|
|
/**
|
|
* Props for DomainDetails component.
|
|
*
|
|
* @public
|
|
*/
|
|
export interface DomainDetailsProps {
|
|
/** Domain data to display */
|
|
domain: Domain
|
|
}
|
|
|
|
/**
|
|
* Props for DomainTimeline component.
|
|
*
|
|
* @public
|
|
*/
|
|
export interface DomainTimelineProps {
|
|
/** Domain data to display timeline for */
|
|
domain: Domain
|
|
}
|
|
|
|
/**
|
|
* Props for DomainFilters component.
|
|
*
|
|
* @public
|
|
*/
|
|
export interface DomainFiltersProps {
|
|
/** Search query change handler */
|
|
onSearchChange: Dispatch<SetStateAction<string>>
|
|
|
|
/** Category filter change handler */
|
|
onCategoryChange: Dispatch<SetStateAction<DomainCategory[]>>
|
|
|
|
/** Status filter change handler */
|
|
onStatusChange: Dispatch<SetStateAction<DomainStatus[]>>
|
|
|
|
/** Registrar filter change handler */
|
|
onRegistrarChange: Dispatch<SetStateAction<DomainRegistrarId[]>>
|
|
|
|
/** Sort option change handler */
|
|
onSortChange: Dispatch<SetStateAction<DomainSortOption>>
|
|
|
|
/** Available registrars for filter options */
|
|
registrars: DomainRegistrarId[]
|
|
}
|