Public types exported and JSDoc-commented

Exported functions and types without JSDoc force every consumer to read the implementation to understand what the module expects, what it returns, and when it throws. ISO 25010:2011 §6.5.2 classifies undocumented public API surfaces as a maintainability defect. In practice, this means every integration with an undocumented utility function is a guess — and wrong guesses about parameter contracts (e.g., whether an ID parameter is the database row ID or the external API ID) produce bugs that only surface in production data.

Add JSDoc to every exported function and public type at module boundaries. Prioritize src/lib/, src/api/, and src/services/ — these are the highest-consumption surfaces.

/**
 * Represents a paginated API response.
 * @template T - The type of items in the results array.
 */
export interface PaginatedResponse<T> {
  /** Items for the current page. */
  items: T[]
  /** Total item count across all pages. */
  total: number
  /** Current page number, 1-indexed. */
  page: number
}

/**
 * Fetches a paginated list of users.
 * @param page - Page number to fetch (1-indexed).
 * @param pageSize - Items per page (default 20, max 100).
 * @returns Paginated user results, or throws UserFetchError on failure.
 */
export async function getUsers(page: number, pageSize = 20): Promise<PaginatedResponse<User>> {
  // ...
}