Documentation

Complete API reference for aidxnCC

ParsedHTML

⌘K

Getting Started

Welcome to the aidxnCC documentation! This reference contains detailed information about all services, utilities, types, and components available in my codebase.

ServicesCore business logic for AI, Device, and Domain management

UtilsUtility functions for formatting, styling, and common operations

TypesTypeScript type definitions and interfaces

ThemeDesign tokens, colors, and surface styles

DevicesDevice specifications and portfolio management

DomainsDomain portfolio and DNS management utilities

DocsDocumentation parsing and search functionality

AIService

classServices

Service for AI usage analytics, token tracking, and cost calculations.

Source

Remarks

Provides comprehensive utilities for analyzing Claude API usage including:

Activity streaks - Track consecutive days of usage
Trend analysis - Linear regression for cost and token projections
Heatmap generation - GitHub-style activity visualization
Time-range filtering - Support for 7d, 1m, 3m, 6m, 1y, all
Model analytics - Usage breakdown by model
Token composition - Input, output, and cache token analysis
Statistics - Comprehensive metrics and aggregations

All date operations use UTC to ensure consistency across timezones.

DeviceService

classServices

Service for managing device data and computing device metrics.

Source

Remarks

Provides a centralized API for device portfolio management including:

Device enrichment with computed metrics (age, category labels)
Filtering by type, manufacturer, status, and release year
Sorting with type-safe key selection
Portfolio statistics and analytics
Related device discovery

All methods are static and operate on the device data store without side effects.

DomainService

classServices

Service for managing domain portfolio data and computing domain metrics.

Source

Remarks

This service provides comprehensive domain portfolio management:

Automatic metric calculation (expiration, ownership duration)
Flexible filtering and sorting
Statistical analysis
Renewal tracking

All date calculations use UTC to ensure consistency across timezones.

lib/github

interfaceServices

GitHub and Forgejo API integration service with server-side caching.

Source

Remarks

This module provides secure, cached access to GitHub and Forgejo APIs for:

Fetching recent repository updates
Retrieving repository metrics (stars, forks)
Managing featured project data

Security Features:

Dual-layer caching (unstable_cache + React cache) prevents API abuse
1-hour revalidation protects GitHub PAT from rate limits
Server-side cache shared across all requests

Environment Variables:

GITHUB_PROJECTS_USER or GITHUB_USERNAME: Override default username
GITHUB_PROJECTS_PAT or GITHUB_PAT: GitHub Personal Access Token (optional)

Properties

Property	Type	Description
GitHubRepoSummary	any	Simplified repository summary for recent repos list.
FeaturedProject	any	Featured project with live metrics from GitHub or Forgejo.
getRecentGitHubRepos	object	Retrieves recently updated GitHub repositories for the configured user. Default: `...`
getFeaturedReposWithMetrics	object	Retrieves featured projects with live star and fork counts. Default: `...`

services

interfaceServices

Source

Properties

Property	Type	Description
DomainService	any	—
DeviceService	any	—
AIService	any	—

services/ai.service

interfaceServices

Source

Properties

Property	Type	Description
HeatmapPalette	any	Configuration for heatmap color palette.
AIStatsResult	any	Comprehensive AI usage statistics and analytics.
AIService	any	Service for AI usage analytics, token tracking, and cost calculations.

services/device.service

interfaceServices

Source

Properties

Property	Type	Description
DevicePortfolioStats	any	Statistics and aggregated metrics for the device portfolio.
DeviceService	any	Service for managing device data and computing device metrics.

services/domain.service

interfaceServices

Source

Properties

Property	Type	Description
DomainService	any	Service for managing domain portfolio data and computing domain metrics.
DomainPortfolioStats	any	Domain portfolio statistics result.

Formatter

classUtils

Formatter utility class providing consistent formatting functions for various data types.

Source

Remarks

This class contains static methods for formatting numbers, dates, strings, and other common data types across the application. All methods are pure functions with no side effects.

isExternalHref

functionUtils

Type guard to check if a URL string is an external link (starts with http/https).

Source

Remarks

This function is useful for conditional rendering of external link attributes or icons. It narrows the TypeScript type to indicate an HTTP(S) URL.

Signature

isExternalHref(href?: string): any

Parameters

Name	Type	Description
href?	string	URL string to check

Returns

any

Type predicate narrowing href to `http${string}` if external

Examples

1import { isExternalHref, externalLinkProps } from '@/lib/utils/styles'
2
3function Link({ href, children }) {
4  const external = isExternalHref(href)
5
6  return (
7    <a href={href} {...(external ? externalLinkProps : {})}>
8      {children}
9      {external && <ExternalIcon />}
10    </a>
11  )
12}

utils

interfaceUtils

Source

Properties

Property	Type	Description
Formatter	any	—
Validator	any	—
externalLinkProps	any	—
isExternalHref	any	—

utils/formatting

interfaceUtils

Source

Properties

Property	Type	Description
Formatter	any	Formatter utility class providing consistent formatting functions for various data types.

utils/styles

interfaceUtils

Source

Properties

Property	Type	Description
externalLinkProps	object	Props to apply to external links for security and UX best practices. Default: `...`
isExternalHref	any	—

utils/validation

interfaceUtils

Source

Properties

Property	Type	Description
Validator	any	Validator utility class providing type-safe validation functions with TypeScript type guards.

Validator

classUtils

Validator utility class providing type-safe validation functions with TypeScript type guards.

Source

Remarks

This class contains static methods for validating various data types and formats. Most methods use TypeScript type predicates for runtime type checking and compile-time type narrowing.

lib/types/ai

interfaceTypes

Type definitions for AI usage analytics and token tracking.

Source

Remarks

This module contains interfaces for Claude AI usage data, including:

Token consumption metrics (input, output, cache)
Cost calculations
Daily aggregations
Trend analysis
Model-specific breakdowns

Properties

Property	Type	Description
ModelBreakdown	any	Breakdown of AI usage metrics for a specific model.
DailyData	any	Aggregated AI usage data for a single day.
Totals	any	Aggregated totals across all time periods.
CCData	any	Complete AI usage dataset with daily breakdowns and totals.
ExtendedCCData	any	Extended AI usage data supporting multiple sources (Claude Code, Codex, etc.).
TimeRangeKey	"7d" \| "1m" \| "3m" \| "6m" \| "1y" \| "all"	Time range selector keys for filtering AI usage data.
HeatmapDay	any	Single day cell data for heatmap visualization.
DailyDataWithTrend	any	Daily data extended with trend analysis for chart visualizations.
ModelUsage	any	Model usage statistics for pie/bar charts.
TokenTypeUsage	any	Token type usage statistics for composition charts.

lib/types/common

interfaceTypes

Common utility types used across my website

Source

Remarks

This module provides fundamental type definitions for date handling, filtering, and pagination. These types are used throughout the application to ensure type safety and consistency.

Properties

Property	Type	Description
DateRange	any	Represents a time range with start and end dates.
FormattedDate	any	Date object with pre-computed formatted strings.

lib/types/device

interfaceTypes

Device type definitions for portfolio showcase. Provides comprehensive type safety for device specifications, statistics, sections, and UI components. Supports both mobile devices and DAPs (Digital Audio Players).

Source

Properties

Property	Type	Description
DeviceIcon	React.ComponentType	Icon component type for device-related icons.
DeviceType	"mobile" \| "dap"	Device type classification.
StarState	"full" \| "half" \| "empty"	Star rating display state.
ExternalHref	any	Type-safe external URL starting with http or https.
DeviceBadge	any	Badge display configuration for device highlights.
DeviceStatItem	any	Individual stat item within a stat group.
DeviceStatGroup	any	Group of related device statistics.
DeviceSectionRow	any	Row item within a device section showing key-value pairs.
DeviceSectionListItem	any	List item within a device section.
DeviceSectionRating	any	Rating configuration for device sections.
DeviceSection	any	Device section containing grouped information.
DeviceSpec	any	Complete device specification. Contains all data needed to render a device page including metadata, statistics, sections, and related devices.
DeviceCollection	Record	Collection of devices indexed by slug.
DeviceWithMetrics	any	Enriched device with computed metrics. Extends DeviceSpec with age calculations and display labels.
DevicePageShellProps	any	Props for DevicePageShell component.
DeviceHeroProps	any	Props for DeviceHero component.
StatsGridProps	any	Props for StatsGrid component.
StatItemProps	any	Props for StatItem component.
SectionsGridProps	any	Props for SectionsGrid component.
SectionCardProps	any	Props for SectionCard component.
SectionRowProps	any	Props for SectionRow component.
RatingProps	any	Props for Rating component.

lib/types/domain

interfaceTypes

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.

Source

Properties

Property	Type	Description
DomainStatus	"active" \| "parked" \| "reserved"	Domain status indicating current usage state.
DomainCategory	"personal" \| "service" \| "project" \| "fun" \| "legacy"	Domain category for portfolio organization.
DomainRegistrarId	"Spaceship" \| "Namecheap" \| "Name.com" \| "Dynadot"	Supported domain registrar identifiers.
DomainSortOption	"name" \| "expiration" \| "ownership" \| "registrar"	Sort options for domain lists.
DomainTimelineEventType	"registration" \| "renewal"	Timeline event types for domain history.
Renewal	any	Domain renewal record tracking renewal history.
RegistrarConfig	any	Registrar configuration for UI display.
Domain	any	Core domain data structure. Base interface containing all raw domain information without computed metrics. Use DomainWithMetrics for enriched data with ownership calculations.
DomainWithMetrics	any	Enriched domain data with computed ownership and expiration metrics. Extends Domain with calculated fields for ownership duration, expiration tracking, and renewal progress.
DomainVisualOption	any	Visual styling configuration for domain status/category badges.
DomainVisualConfig	any	Complete visual configuration mapping for all domain statuses and categories.
DomainRegistrarMap	Record	Mapping of registrar IDs to their configuration.
DomainTimelineEvent	any	Domain timeline event for renewal/registration history display.
DomainCardProps	any	Props for DomainCard component.
DomainDetailsProps	any	Props for DomainDetails component.
DomainTimelineProps	any	Props for DomainTimeline component.
DomainFiltersProps	any	Props for DomainFilters component.

lib/types/service

interfaceTypes

Shared type definitions for service layer operations.

Source

Remarks

This module contains reusable types for common service patterns:

Filtering and sorting configurations
Statistics and aggregation results
Query options and pagination

Properties

Property	Type	Description
SortOrder	"asc" \| "desc"	Sort order direction for list operations.
SortConfig	any	Configuration for sorting operations on typed entities.
FilterConfig	Partial	Generic filter configuration for entity queries.
StatsResult	any	Statistics result containing aggregate metrics.
DateRangeConfig	any	Date range configuration for time-based queries.
PaginationConfig	any	Pagination configuration for list operations.
PaginatedResult	any	Paginated result set with metadata.
QueryOptions	any	Query options combining common patterns.
ServiceResult	any	Service method result wrapper with metadata.
FilterOperator	"eq" \| "ne" \| "gt" \| "gte" \| "lt" \| "lte" \| "in" \| "nin" \| "exists"	Comparison operator for advanced filtering.
FilterExpression	any	Advanced filter expression with operators.