@reallukemanning/folio 1.0.0

package/src/lib/filterByStatus.ts

@@ -0,0 +1,20 @@
+import type { FolioProject, ProjectStatus } from '../types'
+
+export function filterByStatus(
+  projects: FolioProject[],
+  status: ProjectStatus | 'all' | ProjectStatus[] | undefined
+): FolioProject[] {
+  if (projects.length === 0) {
+    return []
+  }
+
+  if (status === 'all' || status === undefined) {
+    return [...projects]
+  }
+
+  if (Array.isArray(status)) {
+    return projects.filter(project => status.includes(project.status))
+  }
+
+  return projects.filter(project => project.status === status)
+}

package/src/lib/filterByType.ts

@@ -0,0 +1,16 @@
+import type { FolioProject, ProjectType } from '../types'
+
+export function filterByType(
+  projects: FolioProject[],
+  type: ProjectType | 'all' | undefined
+): FolioProject[] {
+  if (projects.length === 0) {
+    return []
+  }
+
+  if (type === 'all' || type === undefined) {
+    return [...projects]
+  }
+
+  return projects.filter(project => project.type === type)
+}

package/src/lib/github.ts

@@ -0,0 +1,144 @@
+export interface GitHubRepoData {
+  name: string
+  description: string | null
+  stargazers_count: number
+  forks_count: number
+  language: string | null
+  topics: string[]
+  html_url: string
+  homepage: string | null
+  created_at: string
+  updated_at: string
+  fork?: boolean
+  archived?: boolean
+}
+
+export const LANGUAGE_COLORS: Record<string, string> = {
+  TypeScript: '#3178c6',
+  JavaScript: '#f1e05a',
+  Python: '#3572A5',
+  Java: '#b07219',
+  Go: '#00ADD8',
+  Rust: '#dea584',
+  C: '#555555',
+  'C++': '#f34b7d',
+  'C#': '#239120',
+  PHP: '#4F5D95',
+  Ruby: '#701516',
+  Swift: '#F05138',
+  Kotlin: '#A97BFF',
+  Dart: '#00B4AB',
+  Scala: '#c22d40',
+  Haskell: '#5e5086',
+  Lua: '#000080',
+  Shell: '#89e051',
+  HTML: '#e34c26',
+  CSS: '#563d7c',
+}
+
+export async function fetchGitHubRepo(repo: string): Promise<GitHubRepoData | null> {
+  try {
+    const url = `https://api.github.com/repos/${repo}`
+
+    const headers: HeadersInit = {
+      Accept: 'application/vnd.github.v3+json',
+    }
+
+    const token = process.env.GITHUB_TOKEN
+    if (token) {
+      headers.Authorization = `Bearer ${token}`
+    } else {
+      console.warn('GITHUB_TOKEN not set - using unauthenticated GitHub API (60/hr rate limit)')
+    }
+
+    const response = await fetch(url, {
+      headers,
+      cache: 'force-cache',
+    })
+
+    if (!response.ok) {
+      return null
+    }
+
+    const data = await response.json()
+
+    return {
+      name: data.name,
+      description: data.description,
+      stargazers_count: data.stargazers_count,
+      forks_count: data.forks_count,
+      language: data.language,
+      topics: data.topics || [],
+      html_url: data.html_url,
+      homepage: data.homepage,
+      created_at: data.created_at,
+      updated_at: data.updated_at,
+    }
+  } catch {
+    return null
+  }
+}
+
+export type FetchReposError = 'rate_limit' | 'network' | 'not_found' | 'other'
+
+export interface FetchReposResult {
+  data: GitHubRepoData[] | null
+  error: FetchReposError | null
+  rateLimitRemaining: number | null
+}
+
+export async function fetchGitHubRepos(username: string): Promise<FetchReposResult> {
+  try {
+    const url = `https://api.github.com/users/${username}/repos?sort=updated&per_page=100`
+
+    const headers: HeadersInit = {
+      Accept: 'application/vnd.github.v3+json',
+    }
+
+    const token = process.env.GITHUB_TOKEN
+    if (token) {
+      headers.Authorization = `Bearer ${token}`
+    }
+
+    const response = await fetch(url, {
+      headers,
+    })
+
+    const rateLimitRemaining = response.headers.get('X-RateLimit-Remaining')
+      ? parseInt(response.headers.get('X-RateLimit-Remaining')!)
+      : null
+
+    if (response.status === 403) {
+      return { data: null, error: 'rate_limit', rateLimitRemaining }
+    }
+
+    if (response.status === 404) {
+      return { data: null, error: 'not_found', rateLimitRemaining }
+    }
+
+    if (!response.ok) {
+      return { data: null, error: 'other', rateLimitRemaining }
+    }
+
+    const data = await response.json()
+
+    const repos = data.map((repo: any) => ({
+      name: repo.name,
+      description: repo.description,
+      stargazers_count: repo.stargazers_count,
+      forks_count: repo.forks_count,
+      language: repo.language,
+      topics: repo.topics || [],
+      html_url: repo.html_url,
+      homepage: repo.homepage,
+      fork: repo.fork,
+      archived: repo.archived,
+      created_at: repo.created_at,
+      updated_at: repo.updated_at,
+    }))
+
+    return { data: repos, error: null, rateLimitRemaining }
+  } catch {
+    return { data: null, error: 'network', rateLimitRemaining: null }
+  }
+}

package/src/lib/index.ts

@@ -0,0 +1,15 @@
+export { defineProjects } from './defineProjects'
+export { fetchGitHubRepo, fetchGitHubRepos, LANGUAGE_COLORS } from './github'
+export type { GitHubRepoData, FetchReposResult, FetchReposError } from './github'
+export { fetchNpmPackage } from './npm'
+export { fetchProductHuntPost } from './product-hunt'
+export { filterByFeatured } from './filterByFeatured'
+export { filterByStatus } from './filterByStatus'
+export { filterByType } from './filterByType'
+export { normalise } from './normalise'
+export { sortByDate } from './sortByDate'
+export { sortByName } from './sortByName'
+export { sortByStars } from './sortByStars'
+export type { NpmPackageData } from './npm'
+export type { ProductHuntPostData } from './product-hunt'
+export type { SortOrder } from './sortByDate'

package/src/lib/normalise.ts

@@ -0,0 +1,261 @@
+import { fetchGitHubRepo, LANGUAGE_COLORS } from './github'
+import { fetchNpmPackage } from './npm'
+import { fetchProductHuntPost } from './product-hunt'
+import type { FolioProject, FolioProjectInput, NormalizedStat, ProjectType } from '../types'
+
+export async function normalise(input: FolioProjectInput): Promise<FolioProject> {
+  const {
+    id,
+    type,
+    status,
+    featured,
+    name: inputName,
+    tagline: inputTagline,
+    description: inputDescription,
+    links: inputLinks,
+    stack: inputStack,
+    stats: inputStats,
+    background: inputBackground,
+    why: inputWhy,
+    image: inputImage,
+    struggles: inputStruggles,
+    timeline: inputTimeline,
+    posts: inputPosts,
+    createdAt: inputCreatedAt,
+    updatedAt: inputUpdatedAt,
+    override,
+  } = input
+
+  const repo = 'repo' in input ? input.repo : undefined
+
+  let githubData = null
+
+  if (type === 'github' || type === 'hybrid') {
+    if (repo) {
+      githubData = await fetchGitHubRepo(repo)
+    }
+  }
+
+  const npmPackage = 'package' in input ? input.package : undefined
+
+  let npmData = null
+
+  if (type === 'npm' || type === 'hybrid') {
+    if (npmPackage) {
+      npmData = await fetchNpmPackage(npmPackage)
+    }
+  }
+
+  const slug = 'slug' in input ? input.slug : undefined
+
+  let productHuntData = null
+
+  if (type === 'product-hunt') {
+    if (slug) {
+      productHuntData = await fetchProductHuntPost(slug)
+    }
+  }
+
+  let finalName: string
+  let finalTagline: string
+  let finalDescription: string
+  let finalStack: string[]
+
+  if (type === 'github') {
+    finalName = override?.name || githubData?.name || inputName || ''
+    finalTagline = override?.tagline || inputTagline || ''
+    finalDescription = override?.description || githubData?.description || inputDescription || ''
+    finalStack = override?.stack || inputStack || []
+  } else if (type === 'hybrid') {
+    finalName = override?.name || inputName || githubData?.name || ''
+    finalTagline = override?.tagline || inputTagline || ''
+    finalDescription = override?.description || inputDescription || githubData?.description || ''
+    finalStack = override?.stack || inputStack || []
+  } else {
+    finalName = inputName || ''
+    finalTagline = inputTagline || ''
+    finalDescription = inputDescription || ''
+    finalStack = inputStack || []
+  }
+
+  let finalLinks: FolioProject['links'] = {}
+  if (type === 'github') {
+    if (githubData) {
+      finalLinks = {
+        github: githubData.html_url,
+        live: githubData.homepage || undefined,
+      }
+    }
+    if (inputLinks) {
+      finalLinks = { ...finalLinks, ...inputLinks }
+    }
+  } else if (type === 'hybrid') {
+    finalLinks = inputLinks || {}
+    if (githubData) {
+      finalLinks.github = finalLinks.github || githubData.html_url
+      finalLinks.live = finalLinks.live || githubData.homepage || undefined
+    }
+    if (npmData && npmPackage) {
+      finalLinks.npm = finalLinks.npm || `https://npmjs.com/package/${npmPackage}`
+    }
+  } else {
+    finalLinks = inputLinks || {}
+  }
+
+  let finalStats: FolioProject['stats'] | null = null
+  if (type === 'github' || type === 'hybrid' || type === 'npm' || type === 'product-hunt') {
+    if (githubData) {
+      finalStats = {
+        stars: githubData.stargazers_count,
+        forks: githubData.forks_count,
+      }
+    }
+    if (npmData) {
+      finalStats = {
+        ...finalStats,
+        downloads: String(npmData.downloads),
+        version: npmData.version,
+      }
+    }
+    if (productHuntData) {
+      finalStats = {
+        ...finalStats,
+        upvotes: productHuntData.votes_count,
+        comments: productHuntData.comments_count,
+        launchDate: productHuntData.featured_at || undefined,
+      }
+    }
+    if (inputStats) {
+      finalStats = { ...finalStats, ...inputStats }
+    }
+  } else {
+    finalStats = inputStats || null
+  }
+
+  let finalLanguage: FolioProject['language'] = null
+  let finalLanguageColor: FolioProject['languageColor'] = null
+  let finalCreatedAt: FolioProject['createdAt'] = null
+  let finalUpdatedAt: FolioProject['updatedAt'] = null
+
+  if (type === 'github') {
+    finalLanguage = githubData?.language || null
+    finalLanguageColor = githubData?.language ? LANGUAGE_COLORS[githubData.language] || null : null
+    finalCreatedAt = githubData?.created_at || inputCreatedAt || null
+    finalUpdatedAt = githubData?.updated_at || inputUpdatedAt || null
+  } else if (type === 'hybrid') {
+    finalLanguage = githubData?.language || null
+    finalLanguageColor = githubData?.language ? LANGUAGE_COLORS[githubData.language] || null : null
+    finalCreatedAt = githubData?.created_at || inputCreatedAt || null
+    finalUpdatedAt = githubData?.updated_at || inputUpdatedAt || null
+  } else {
+    finalLanguage = null
+    finalLanguageColor = null
+    finalCreatedAt = inputCreatedAt || null
+    finalUpdatedAt = inputUpdatedAt || null
+  }
+
+  return {
+    id,
+    type,
+    status,
+    featured: featured || false,
+    name: finalName,
+    tagline: finalTagline,
+    description: finalDescription,
+    background: inputBackground || null,
+    why: inputWhy || null,
+    image: inputImage || null,
+    struggles: inputStruggles || [],
+    timeline: inputTimeline || [],
+    posts: inputPosts || [],
+    stack: finalStack,
+    links: finalLinks,
+    stats: finalStats,
+    language: finalLanguage,
+    languageColor: finalLanguageColor,
+    createdAt: finalCreatedAt,
+    updatedAt: finalUpdatedAt,
+    repo,
+    package: npmPackage,
+    slug: 'slug' in input ? input.slug : undefined,
+  }
+}
+
+function formatNumber(value: number): string {
+  if (value >= 1000000) {
+    return (value / 1000000).toFixed(1) + 'M'
+  }
+  if (value >= 1000) {
+    return (value / 1000).toFixed(1) + 'K'
+  }
+  return value.toString()
+}
+
+function formatDate(value: string | number): string {
+  try {
+    const date = new Date(value)
+    if (isNaN(date.getTime())) {
+      return String(value)
+    }
+    return date.toLocaleDateString('en-US', {
+      year: 'numeric',
+      month: 'short',
+      day: 'numeric',
+    })
+  } catch {
+    return String(value)
+  }
+}
+
+export function normalizeStats(stats: Record<string, unknown>, _type: ProjectType): NormalizedStat[] {
+  const result: NormalizedStat[] = []
+
+  if (stats.stars !== undefined && stats.stars !== null) {
+    const value = Number(stats.stars)
+    if (!isNaN(value)) {
+      result.push({ label: 'Stars', value: formatNumber(value) })
+    }
+  }
+
+  if (stats.forks !== undefined && stats.forks !== null) {
+    const value = Number(stats.forks)
+    if (!isNaN(value)) {
+      result.push({ label: 'Forks', value: formatNumber(value) })
+    }
+  }
+
+  if (stats.downloads !== undefined && stats.downloads !== null) {
+    const value = Number(stats.downloads)
+    if (!isNaN(value)) {
+      result.push({ label: 'Downloads', value: formatNumber(value), unit: 'month' })
+    }
+  }
+
+  if (stats.version !== undefined && stats.version !== null) {
+    let version = String(stats.version)
+    if (version && !version.startsWith('v')) {
+      version = 'v' + version
+    }
+    result.push({ label: 'Version', value: version })
+  }
+
+  if (stats.upvotes !== undefined && stats.upvotes !== null) {
+    const value = Number(stats.upvotes)
+    if (!isNaN(value)) {
+      result.push({ label: 'Upvotes', value: formatNumber(value) })
+    }
+  }
+
+  if (stats.comments !== undefined && stats.comments !== null) {
+    const value = Number(stats.comments)
+    if (!isNaN(value)) {
+      result.push({ label: 'Comments', value: formatNumber(value) })
+    }
+  }
+
+  if (stats.launchDate !== undefined && stats.launchDate !== null) {
+    result.push({ label: 'Launched', value: formatDate(String(stats.launchDate)) })
+  }
+
+  return result
+}

package/src/lib/npm.ts

@@ -0,0 +1,38 @@
+export interface NpmPackageData {
+  name: string
+  version: string
+  downloads: number
+}
+
+export async function fetchNpmPackage(packageName: string): Promise<NpmPackageData | null> {
+  try {
+    const downloadsUrl = `https://api.npmjs.org/downloads/point/last-month/${packageName}`
+    const registryUrl = `https://registry.npmjs.org/${packageName}`
+
+    const [downloadsResponse, registryResponse] = await Promise.all([
+      fetch(downloadsUrl, { cache: 'force-cache' }),
+      fetch(registryUrl, { cache: 'force-cache' }),
+    ])
+
+    if (!downloadsResponse.ok || !registryResponse.ok) {
+      return null
+    }
+
+    const downloadsData = await downloadsResponse.json()
+    const registryData = await registryResponse.json()
+
+    const version = registryData['dist-tags']?.latest
+
+    if (!version) {
+      return null
+    }
+
+    return {
+      name: downloadsData.package || packageName,
+      version,
+      downloads: downloadsData.downloads || 0,
+    }
+  } catch {
+    return null
+  }
+}

package/src/lib/product-hunt.ts

@@ -0,0 +1,57 @@
+export interface ProductHuntPostData {
+  name: string
+  tagline: string
+  description: string
+  votes_count: number
+  comments_count: number
+  featured_at: string | null
+  website: string
+  url: string
+}
+
+export async function fetchProductHuntPost(slug: string): Promise<ProductHuntPostData | null> {
+  try {
+    const url = `https://api.producthunt.com/v2/posts/${slug}`
+
+    const token = process.env.PRODUCT_HUNT_TOKEN
+    if (!token) {
+      console.warn('PRODUCT_HUNT_TOKEN not set - cannot fetch Product Hunt data')
+      return null
+    }
+
+    const headers: HeadersInit = {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/json',
+    }
+
+    const response = await fetch(url, {
+      headers,
+      cache: 'force-cache',
+    })
+
+    if (!response.ok) {
+      return null
+    }
+
+    const data = await response.json()
+
+    const post = data.post
+
+    if (!post) {
+      return null
+    }
+
+    return {
+      name: post.name,
+      tagline: post.tagline,
+      description: post.description || '',
+      votes_count: post.votes_count || 0,
+      comments_count: post.comments_count || 0,
+      featured_at: post.featured_at || null,
+      website: post.website || '',
+      url: post.url || '',
+    }
+  } catch {
+    return null
+  }
+}

package/src/lib/sortByDate.ts

@@ -0,0 +1,30 @@
+import type { FolioProject } from '../types'
+
+export type SortOrder = 'asc' | 'desc'
+
+export function sortByDate(projects: FolioProject[], order: SortOrder = 'desc'): FolioProject[] {
+  if (projects.length === 0) {
+    return []
+  }
+
+  const multiplier = order === 'asc' ? 1 : -1
+
+  return [...projects].sort((a, b) => {
+    const dateA = a.updatedAt || a.createdAt || null
+    const dateB = b.updatedAt || b.createdAt || null
+
+    if (!dateA && !dateB) {
+      return 0
+    }
+
+    if (!dateA) {
+      return 1 * multiplier
+    }
+
+    if (!dateB) {
+      return -1 * multiplier
+    }
+
+    return (new Date(dateA).getTime() - new Date(dateB).getTime()) * multiplier
+  })
+}

package/src/lib/sortByName.ts

@@ -0,0 +1,29 @@
+import type { FolioProject } from '../types'
+import type { SortOrder } from './sortByDate'
+
+export function sortByName(projects: FolioProject[], order: SortOrder = 'asc'): FolioProject[] {
+  if (projects.length === 0) {
+    return []
+  }
+
+  const multiplier = order === 'asc' ? 1 : -1
+
+  return [...projects].sort((a, b) => {
+    const nameA = a.name ?? null
+    const nameB = b.name ?? null
+
+    if (!nameA && !nameB) {
+      return 0
+    }
+
+    if (!nameA) {
+      return 1
+    }
+
+    if (!nameB) {
+      return -1
+    }
+
+    return nameA.localeCompare(nameB, undefined, { sensitivity: 'base' }) * multiplier
+  })
+}

package/src/lib/sortByStars.ts

@@ -0,0 +1,29 @@
+import type { FolioProject } from '../types'
+import type { SortOrder } from './sortByDate'
+
+export function sortByStars(projects: FolioProject[], order: SortOrder = 'desc'): FolioProject[] {
+  if (projects.length === 0) {
+    return []
+  }
+
+  const multiplier = order === 'asc' ? 1 : -1
+
+  return [...projects].sort((a, b) => {
+    const starsA = a.type === 'github' ? (a.stats?.stars ?? 0) : 0
+    const starsB = b.type === 'github' ? (b.stats?.stars ?? 0) : 0
+
+    if (starsA === 0 && starsB === 0) {
+      return 0
+    }
+
+    if (starsA === 0) {
+      return 1
+    }
+
+    if (starsB === 0) {
+      return -1
+    }
+
+    return (starsA - starsB) * multiplier
+  })
+}

package/src/test-setup.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom/vitest'