// lib/utils/db-editor-stubs.ts
// ─── STUB IMPLEMENTATIONS ────────────────────────────────────────────────
// These are placeholder functions that the dynamic components import.
// The AI implementing this template MUST wire these to the target site's
// actual database queries. See DB_FUNCTIONS.md for the expected return shapes.

export interface ArticleStub {
  slug: string;
  title: string;
  cardImage?: string;
  excerpt?: string;
  category?: string;
  author?: string;
  publishedAt?: Date | string;
  readingTime?: number;
}

export interface AuthorInfoStub {
  authorBio?: string;
  authorAvatar?: string;
  authorRole?: string;
  authorProfileUrl?: string;
  socialTwitter?: string;
  socialInstagram?: string;
  socialYoutube?: string;
  socialLinkedin?: string;
  socialWebsite?: string;
}

export interface CategoryWithCount {
  name: string;
  count: number;
}

/**
 * Returns the N most recent articles ordered by publishedAt DESC.
 * Used by: BlogGrid, HeroBlogCarousel, BlogShowcaseGrid
 */
export async function getLatestArticles(count: number): Promise<ArticleStub[]> {
  // TODO: Replace with actual DB query
  return [];
}

/**
 * Returns the N "trending" articles (e.g., most viewed in last 7 days).
 * Used by: ArticleGridTrendingRanking, TwoColumnLayout
 */
export async function getTrendingArticles(count: number): Promise<ArticleStub[]> {
  // TODO: Replace with actual DB query
  return [];
}

/**
 * Returns the N most-read articles of all time.
 * Used by: ArticleGridTrendingRanking, TwoColumnLayout, BlogShowcaseGrid
 */
export async function getMostReadArticles(count: number): Promise<ArticleStub[]> {
  // TODO: Replace with actual DB query
  return [];
}

/**
 * Returns a single "featured" article (the one with the featured flag set).
 * Used by: FeaturedArticleHero
 */
export async function getFeaturedArticle(): Promise<ArticleStub | null> {
  // TODO: Replace with actual DB query
  return null;
}

/**
 * Returns N featured articles (all articles with the featured flag).
 * Used by: FeaturedArticleSpotlight
 */
export async function getFeaturedArticles(count: number): Promise<ArticleStub[]> {
  // TODO: Replace with actual DB query
  return [];
}

/**
 * Returns the primary/default author name for the site.
 * Used by: AuthorBox
 */
export async function getPrimaryAuthor(): Promise<string> {
  // TODO: Replace with actual DB query or site config
  return '編集部';
}

/**
 * Returns author info (bio, avatar) for a given author name.
 * Used by: AuthorBox
 */
export async function getAuthorInfo(authorName: string): Promise<AuthorInfoStub | null> {
  // TODO: Replace with actual DB query
  return null;
}

/**
 * Returns all categories with their article counts.
 * Used by: ArticleGridCategorySections
 */
export async function getAllCategoriesWithCount(): Promise<CategoryWithCount[]> {
  // TODO: Replace with actual DB query
  return [];
}

/**
 * Returns N articles for a specific category.
 * Used by: ArticleGridCategorySections
 */
export async function getCategoryArticles(categoryName: string, limit: number): Promise<ArticleStub[]> {
  // TODO: Replace with actual DB query
  return [];
}
