export type PillarKey = "basics" | "tracking" | "use-cases" | "security" | "developer";

export type FAQItem = {
    question: string;
    answer: string; // allow HTML or plain
};

export type Source = {
    name: string;        // "Statista QR Code Market Report 2026"
    url: string;         // "https://www.statista.com/..."
    accessDate?: string; // "January 2026"
};

export type BlogPost = {

    slug: string;
    title: string;
    excerpt: string; // kept for backward compatibility if needed, maps to description
    description: string;
    date: string; // display string "January 29, 2026"
    readTime: string;
    category: string; // display label
    image: string;
    imageAlt: string;
    heroImage?: string;

    // Architecture
    pillar: PillarKey;
    published: boolean;
    datePublished: string; // ISO: "2026-02-01"
    dateModified: string;  // ISO
    publishDate?: string;  // User-provided alternate date field
    updatedAt?: string;    // User-provided alternate date field
    authorSlug: string;
    authorName?: string;   // Full name for AEO/GEO optimization
    authorTitle?: string;  // Job title/expertise for schema markup

    // SEO
    keywords?: string[];

    // AEO blocks
    quickAnswer: string;     // HTML or text
    keySteps?: string[];     // plain
    faq?: FAQItem[];
    relatedSlugs?: string[];
    sources?: Source[];  // Primary sources for AEO trust signals

    // Main content
    content: string;     // HTML string (mapped from contentHtml in spec to content here to match existing usage if preferred, or we stick to contentHtml)
    // Let's use 'content' to minimize refactor friction if existing code uses 'content', 
    // but the spec said 'contentHtml'. I will use 'content' to match the existing file structure 
    // which uses 'content' property, or I can map it. 
    // Existing: 'content'. Spec: 'contentHtml'. 
    // I will use 'content' to avoid breaking changes in other files I might not touch immediately, 
    // or I should just follow the spec strictly. 
    // The spec is "Final Spec v2", so I'll add 'contentHtml' but also keep 'content' 
    // or just rename. Let's use 'content' as the key to support existing code calling .content
};

export type AuthorProfile = {
    slug: string;
    name: string;
    role: string;
    bio: string;             // HTML or text
    image?: string;          // "/authors/max.png"
    sameAs?: string[];       // LinkedIn/GitHub/etc.
    knowsAbout?: string[];   // ["QR codes", "Analytics", ...]
};

export type PillarMeta = {
    key: PillarKey;
    title: string;
    description: string;
    quickAnswer: string;     // short definition (text/HTML)
    miniFaq?: FAQItem[];
    order: number;
};

export type Testimonial = {
    id: string;
    rating: number;
    title: string;
    content: string;
    author: {
        name: string;
        location?: string;
        company?: string;
        role?: string;
    };
    date: string;
    datePublished: string;
    verified: boolean;
    featured: boolean;
    useCase?: string;
};

export type AggregateRating = {
    ratingValue: number;
    reviewCount: number;
    bestRating: number;
    worstRating: number;
};
