Etsy Seo

#!/usr/bin/env python3
"""
Etsy SEO Analyzer - Core Engine
Etsy SEO Analyze - Core Engine

Features:
- SEO Overall Rating (0-100)
- TitleOptimization Suggestions
- 13 TagRecommended
- DescriptionOptimization Suggestions
- KeywordsResearch
- Competitor SEO Analyze
- Store SEO Optimization
- Attribute fillingCheck

Version: 1.0.0
"""

import json
import re
from dataclasses import dataclass, field
from typing import List, Dict, Optional, Tuple
from enum import Enum
from collections import Counter
import sys


class SEOGrade(Enum):
    """SEO Grade"""
    EXCELLENT = "A"   # 90-100
    GOOD = "B"        # 70-89
    AVERAGE = "C"     # 50-69
    POOR = "D"        # 30-49
    CRITICAL = "F"    # 0-29


# ============================================================
# Etsy PopularKeywordsLibrary (By category)
# ============================================================

ETSY_KEYWORDS = {
    "jewelry": [
        "handmade jewelry", "personalized necklace", "custom bracelet",
        "birthstone ring", "minimalist earrings", "gold filled",
        "sterling silver", "dainty jewelry", "layered necklace",
        "initial jewelry", "gift for her", "bridesmaid gift",
    ],
    "home_decor": [
        "wall art", "home decor", "farmhouse decor", "boho decor",
        "personalized sign", "custom portrait", "macrame", "plant holder",
        "candle holder", "throw pillow", "wall hanging", "housewarming gift",
    ],
    "clothing": [
        "vintage clothing", "handmade dress", "boho style", "linen clothing",
        "custom t-shirt", "embroidered", "sustainable fashion", "cottagecore",
        "oversized sweater", "matching set", "loungewear", "festival outfit",
    ],
    "accessories": [
        "leather wallet", "handmade bag", "personalized keychain",
        "phone case", "hair accessories", "scrunchie", "tote bag",
        "crossbody bag", "beanie", "scarf", "belt", "sunglasses chain",
    ],
    "art": [
        "digital download", "printable art", "wall print", "custom portrait",
        "pet portrait", "watercolor", "illustration", "line art",
        "minimalist art", "abstract art", "nursery art", "office decor",
    ],
    "craft_supplies": [
        "beads", "charms", "fabric", "yarn", "patterns", "stickers",
        "stamps", "dies", "embellishments", "ribbon", "findings",
    ],
    "wedding": [
        "wedding invitation", "bridal jewelry", "bridesmaid gift",
        "wedding decor", "cake topper", "guest book", "veil",
        "wedding favor", "flower girl", "groomsmen gift", "engagement",
    ],
    "default": [
        "handmade", "custom", "personalized", "gift", "unique",
        "vintage", "boho", "minimalist", "eco friendly", "sustainable",
    ],
}

# Long-tailKeywordsTemplate
LONG_TAIL_TEMPLATES = [
    "{keyword} for women",
    "{keyword} for men",
    "{keyword} gift",
    "personalized {keyword}",
    "custom {keyword}",
    "handmade {keyword}",
    "{keyword} for mom",
    "{keyword} for her",
    "{keyword} for him",
    "vintage {keyword}",
]


# ============================================================
# Data Structures
# ============================================================

@dataclass
class ListingInfo:
    """ProductInformation"""
    title: str = ""
    tags: List[str] = field(default_factory=list)
    description: str = ""
    category: str = "default"
    attributes: Dict[str, str] = field(default_factory=dict)
    price: float = 0.0
    images: int = 0
    image_alts: List[str] = field(default_factory=list)
    url: str = ""


@dataclass
class ShopInfo:
    """StoreInformation"""
    name: str = ""
    announcement: str = ""
    about: str = ""
    policies: str = ""
    sections: List[str] = field(default_factory=list)


@dataclass
class SEOScore:
    """SEO Rating"""
    total: int = 0
    grade: SEOGrade = SEOGrade.CRITICAL
    title_score: int = 0
    tags_score: int = 0
    description_score: int = 0
    attributes_score: int = 0
    images_score: int = 0


@dataclass
class TitleAnalysis:
    """TitleAnalyze"""
    length: int = 0
    max_length: int = 140
    keyword_count: int = 0
    has_main_keyword: bool = False
    readability: str = ""
    issues: List[str] = field(default_factory=list)
    suggestions: List[str] = field(default_factory=list)
    optimized_title: str = ""


@dataclass
class TagsAnalysis:
    """TagAnalyze"""
    count: int = 0
    max_count: int = 13
    avg_length: float = 0.0
    long_tail_count: int = 0
    missing_count: int = 0
    issues: List[str] = field(default_factory=list)
    suggested_tags: List[str] = field(default_factory=list)


@dataclass
class DescriptionAnalysis:
    """DescriptionAnalyze"""
    length: int = 0
    first_160_chars: str = ""
    keyword_density: float = 0.0
    has_call_to_action: bool = False
    issues: List[str] = field(default_factory=list)
    suggestions: List[str] = field(default_factory=list)


@dataclass
class SEOReport:
    """SEO AnalyzeReport"""
    listing: ListingInfo
    score: SEOScore
    title_analysis: TitleAnalysis
    tags_analysis: TagsAnalysis
    description_analysis: DescriptionAnalysis
    keyword_suggestions: List[str]
    competitor_insights: List[str]
    action_items: List[Dict]
    summary: str
    summary_zh: str


# ============================================================
# AnalyzeFunction
# ============================================================

def analyze_title(title: str, category: str) -> Tuple[int, TitleAnalysis]:
    """AnalyzeTitle"""
    analysis = TitleAnalysis()
    analysis.length = len(title)
    issues = []
    suggestions = []
    score = 100
    
    # DegreeCheck (Etsy Restriction 140 Character)
    if analysis.length < 40:
        issues.append("Title too short (< 40 chars)")
        score -= 20
    elif analysis.length > 140:
        issues.append("Title exceeds 140 character limit")
        score -= 30
    elif analysis.length < 80:
        suggestions.append("Consider using more characters (ideal: 80-140)")
        score -= 5
    
    # KeywordsCheck
    category_keywords = ETSY_KEYWORDS.get(category, ETSY_KEYWORDS["default"])
    title_lower = title.lower()
    
    found_keywords = [kw for kw in category_keywords if kw.lower() in title_lower]
    analysis.keyword_count = len(found_keywords)
    analysis.has_main_keyword = analysis.keyword_count > 0
    
    if not analysis.has_main_keyword:
        issues.append("No category keywords found in title")
        score -= 25
    elif analysis.keyword_count < 2:
        suggestions.append("Add more relevant keywords")
        score -= 10
    
    # CanReadabilityCheck
    words = title.split()
    if len(words) < 5:
        issues.append("Title has too few words")
        score -= 15
    
    # Special charactersCheck
    if re.search(r'[!@#$%^&*()_+=\[\]{}|\\:";\'<>?/]', title):
        suggestions.append("Avoid special characters in title")
        score -= 5
    
    #  all  big writeCheck
    if title.isupper():
        issues.append("Avoid ALL CAPS in title")
        score -= 15
    
    analysis.issues = issues
    analysis.suggestions = suggestions
    analysis.readability = "Good" if len(issues) == 0 else "Needs improvement"
    
    # GenerateOptimization SuggestionsTitle
    if not analysis.has_main_keyword and category_keywords:
        base_keyword = category_keywords[0]
        analysis.optimized_title = f"{base_keyword.title()}, {title}"[:140]
    
    return max(0, score), analysis


def analyze_tags(tags: List[str], category: str) -> Tuple[int, TagsAnalysis]:
    """AnalyzeTag"""
    analysis = TagsAnalysis()
    analysis.count = len(tags)
    issues = []
    score = 100
    
    # QuantityCheck (Etsy Allow 13 )
    analysis.missing_count = 13 - analysis.count
    if analysis.count < 13:
        issues.append(f"Only {analysis.count}/13 tags used")
        score -= (13 - analysis.count) * 5
    
    # DegreeAnalyze
    if tags:
        lengths = [len(tag) for tag in tags]
        analysis.avg_length = sum(lengths) / len(lengths)
        
        # Check  short Tag
        short_tags = [t for t in tags if len(t) < 5]
        if short_tags:
            issues.append(f"{len(short_tags)} tags are too short")
            score -= len(short_tags) * 3
        
        # ChecksuperTag (20 Character limit)
        long_tags = [t for t in tags if len(t) > 20]
        if long_tags:
            issues.append(f"{len(long_tags)} tags exceed 20 characters")
            score -= len(long_tags) * 5
    
    # Long-tailKeywordsCheck
    analysis.long_tail_count = len([t for t in tags if ' ' in t])
    if analysis.long_tail_count < 5:
        issues.append("Need more multi-word (long-tail) tags")
        score -= 10
    
    #  heavy complexCheck
    unique_tags = set(t.lower() for t in tags)
    if len(unique_tags) < len(tags):
        issues.append("Duplicate tags found")
        score -= 10
    
    analysis.issues = issues
    
    # GenerateRecommendedTag
    category_keywords = ETSY_KEYWORDS.get(category, ETSY_KEYWORDS["default"])
    existing_lower = set(t.lower() for t in tags)
    
    suggested = []
    for kw in category_keywords:
        if kw.lower() not in existing_lower and len(suggested) < analysis.missing_count:
            suggested.append(kw)
    
    # AddLong-tailVariant
    if suggested and len(suggested) < analysis.missing_count:
        base = suggested[0].split()[0] if suggested else category_keywords[0]
        for template in LONG_TAIL_TEMPLATES:
            tag = template.format(keyword=base)
            if len(tag) <= 20 and tag.lower() not in existing_lower:
                suggested.append(tag)
                if len(suggested) >= analysis.missing_count:
                    break
    
    analysis.suggested_tags = suggested[:analysis.missing_count]
    
    return max(0, score), analysis


def analyze_description(description: str, category: str) -> Tuple[int, DescriptionAnalysis]:
    """AnalyzeDescription"""
    analysis = DescriptionAnalysis()
    analysis.length = len(description)
    issues = []
    suggestions = []
    score = 100
    
    # DegreeCheck
    if analysis.length < 100:
        issues.append("Description too short (< 100 chars)")
        score -= 30
    elif analysis.length < 300:
        suggestions.append("Consider a longer description (300+ chars)")
        score -= 10
    
    #  before  160 CharacterCheck (SearchEngineSummary)
    analysis.first_160_chars = description[:160]
    
    # KeywordsdenseDegree
    category_keywords = ETSY_KEYWORDS.get(category, ETSY_KEYWORDS["default"])
    desc_lower = description.lower()
    keyword_count = sum(1 for kw in category_keywords if kw.lower() in desc_lower)
    analysis.keyword_density = keyword_count / max(1, len(description.split())) * 100
    
    if keyword_count == 0:
        issues.append("No category keywords in description")
        score -= 20
    
    # CTA Check
    cta_phrases = ["shop now", "buy now", "order today", "click", "add to cart", "check out", "contact"]
    analysis.has_call_to_action = any(cta in desc_lower for cta in cta_phrases)
    if not analysis.has_call_to_action:
        suggestions.append("Add a call-to-action")
        score -= 5
    
    # ParagraphCheck
    if '\n' not in description and analysis.length > 200:
        suggestions.append("Break into paragraphs for readability")
        score -= 5
    
    analysis.issues = issues
    analysis.suggestions = suggestions
    
    return max(0, score), analysis


def calculate_seo_score(
    title_score: int,
    tags_score: int,
    desc_score: int,
    attr_score: int,
    img_score: int
) -> SEOScore:
    """CalculateComprehensive SEO Rating"""
    
    # Weight: Title30%, Tag25%, Description20%, Property15%, Image10%
    total = int(
        title_score * 0.30 +
        tags_score * 0.25 +
        desc_score * 0.20 +
        attr_score * 0.15 +
        img_score * 0.10
    )
    
    if total >= 90:
        grade = SEOGrade.EXCELLENT
    elif total >= 70:
        grade = SEOGrade.GOOD
    elif total >= 50:
        grade = SEOGrade.AVERAGE
    elif total >= 30:
        grade = SEOGrade.POOR
    else:
        grade = SEOGrade.CRITICAL
    
    return SEOScore(
        total=total,
        grade=grade,
        title_score=title_score,
        tags_score=tags_score,
        description_score=desc_score,
        attributes_score=attr_score,
        images_score=img_score,
    )


def generate_action_items(
    title_analysis: TitleAnalysis,
    tags_analysis: TagsAnalysis,
    desc_analysis: DescriptionAnalysis,
    score: SEOScore
) -> List[Dict]:
    """GenerateActionRecommendation"""
    actions = []
    
    # TitleIssue
    for issue in title_analysis.issues:
        actions.append({
            "category": "Title",
            "category_zh": "Title",
            "priority": "P1",
            "action": f"Fix: {issue}",
            "action_zh": f"Fix: {issue}",
        })
    
    # TagIssue
    if tags_analysis.missing_count > 0:
        actions.append({
            "category": "Tags",
            "category_zh": "Tag",
            "priority": "P1",
            "action": f"Add {tags_analysis.missing_count} more tags",
            "action_zh": f"Add {tags_analysis.missing_count} Tag",
        })
    
    for issue in tags_analysis.issues:
        if "missing" not in issue.lower():
            actions.append({
                "category": "Tags",
                "category_zh": "Tag",
                "priority": "P2",
                "action": f"Fix: {issue}",
                "action_zh": f"Fix: {issue}",
            })
    
    # DescriptionIssue
    for issue in desc_analysis.issues:
        actions.append({
            "category": "Description",
            "category_zh": "Description",
            "priority": "P2",
            "action": f"Fix: {issue}",
            "action_zh": f"Fix: {issue}",
        })
    
    return actions


def analyze_listing(listing: ListingInfo) -> SEOReport:
    """AnalyzeProduct SEO"""
    
    # Analyze each Part
    title_score, title_analysis = analyze_title(listing.title, listing.category)
    tags_score, tags_analysis = analyze_tags(listing.tags, listing.category)
    desc_score, desc_analysis = analyze_description(listing.description, listing.category)
    
    # PropertyRating (simple)
    attr_score = 100 if len(listing.attributes) >= 5 else len(listing.attributes) * 20
    
    # ImageRating
    img_score = min(100, listing.images * 10) if listing.images > 0 else 0
    
    # Overall Rating
    score = calculate_seo_score(title_score, tags_score, desc_score, attr_score, img_score)
    
    # KeywordsRecommendation
    category_keywords = ETSY_KEYWORDS.get(listing.category, ETSY_KEYWORDS["default"])
    keyword_suggestions = category_keywords[:10]
    
    # ActionRecommendation
    action_items = generate_action_items(title_analysis, tags_analysis, desc_analysis, score)
    
    # Summary
    summary = f"SEO Score: {score.total}/100 ({score.grade.value}) | Title: {title_score} | Tags: {tags_score} | Desc: {desc_score}"
    summary_zh = f"SEO Rating: {score.total}/100 ({score.grade.value}) | Title: {title_score} | Tag: {tags_score} | Description: {desc_score}"
    
    return SEOReport(
        listing=listing,
        score=score,
        title_analysis=title_analysis,
        tags_analysis=tags_analysis,
        description_analysis=desc_analysis,
        keyword_suggestions=keyword_suggestions,
        competitor_insights=[],
        action_items=action_items,
        summary=summary,
        summary_zh=summary_zh,
    )


# ============================================================
# OutputFormat
# ============================================================

def format_report(report: SEOReport, lang: str = "en") -> str:
    """FormatReport"""
    s = report.score
    t = report.title_analysis
    tg = report.tags_analysis
    d = report.description_analysis
    
    grade_colors = {"A": "🟢", "B": "🔵", "C": "🟡", "D": "🟠", "F": "🔴"}
    grade_icon = grade_colors.get(s.grade.value, "⚪")
    
    if lang == "zh":
        lines = [
            "🏷️ **Etsy SEO AnalyzeReport**",
            "",
            f"**Product**: {report.listing.title[:50]}...",
            f"**Category**: {report.listing.category}",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            f"## {grade_icon} SEO Overall Rating: {s.total}/100 (Grade {s.grade.value})",
            "",
            "| dimensionDegree | Score | Weight |",
            "|------|------|------|",
            f"| Title | {s.title_score}/100 | 30% |",
            f"| Tag | {s.tags_score}/100 | 25% |",
            f"| Description | {s.description_score}/100 | 20% |",
            f"| Property | {s.attributes_score}/100 | 15% |",
            f"| Image | {s.images_score}/100 | 10% |",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 📝 TitleAnalyze",
            "",
            f"**Degree**: {t.length}/{t.max_length} Character",
            f"**Keywords**: {t.keyword_count} ",
            f"**CanReadability**: {t.readability}",
            "",
        ]
        
        if t.issues:
            lines.append("**Issue:**")
            for issue in t.issues:
                lines.append(f"- ❌ {issue}")
            lines.append("")
        
        if t.suggestions:
            lines.append("**Recommendation:**")
            for sug in t.suggestions:
                lines.append(f"- 💡 {sug}")
            lines.append("")
        
        if t.optimized_title:
            lines.extend([
                "**Optimization after TitleExample:**",
                f"```{t.optimized_title}```",
                "",
            ])
        
        lines.extend([
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 🏷️ TagAnalyze",
            "",
            f"** already Use**: {tg.count}/13 ",
            f"**Long-tail Keywords**: {tg.long_tail_count} ",
            f"**AverageDegree**: {tg.avg_length:.1f} Character",
            "",
        ])
        
        if tg.issues:
            lines.append("**Issue:**")
            for issue in tg.issues:
                lines.append(f"- ❌ {issue}")
            lines.append("")
        
        if tg.suggested_tags:
            lines.extend([
                "**RecommendedAddTag:**",
                "",
            ])
            for i, tag in enumerate(tg.suggested_tags, 1):
                lines.append(f"{i}. `{tag}`")
            lines.append("")
        
        lines.extend([
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 📄 DescriptionAnalyze",
            "",
            f"**Degree**: {d.length} Character",
            f"**KeywordsdenseDegree**: {d.keyword_density:.1f}%",
            f"** has  CTA**: {'✅  is ' if d.has_call_to_action else '❌ no'}",
            "",
        ])
        
        if d.issues or d.suggestions:
            for issue in d.issues:
                lines.append(f"- ❌ {issue}")
            for sug in d.suggestions:
                lines.append(f"- 💡 {sug}")
            lines.append("")
        
        if report.keyword_suggestions:
            lines.extend([
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## 🔑 RecommendedKeywords",
                "",
                ", ".join([f"`{kw}`" for kw in report.keyword_suggestions[:8]]),
                "",
            ])
        
        if report.action_items:
            lines.extend([
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## 📋 Action Plan",
                "",
            ])
            for action in report.action_items[:5]:
                lines.append(f"**[{action['priority']}] [{action['category_zh']}]** {action['action_zh']}")
            lines.append("")
        
        lines.extend([
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            report.summary_zh,
        ])
    else:
        # English version (similar structure)
        lines = [
            "🏷️ **Etsy SEO Analysis Report**",
            "",
            f"**Listing**: {report.listing.title[:50]}...",
            f"**Category**: {report.listing.category}",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            f"## {grade_icon} SEO Score: {s.total}/100 (Grade {s.grade.value})",
            "",
            "| Dimension | Score | Weight |",
            "|-----------|-------|--------|",
            f"| Title | {s.title_score}/100 | 30% |",
            f"| Tags | {s.tags_score}/100 | 25% |",
            f"| Description | {s.description_score}/100 | 20% |",
            f"| Attributes | {s.attributes_score}/100 | 15% |",
            f"| Images | {s.images_score}/100 | 10% |",
            "",
            "## 📝 Title Analysis",
            f"Length: {t.length}/{t.max_length} | Keywords: {t.keyword_count}",
            "",
        ]
        
        if t.issues:
            for issue in t.issues:
                lines.append(f"- ❌ {issue}")
        
        if tg.suggested_tags:
            lines.extend([
                "",
                "## 🏷️ Suggested Tags",
                ", ".join([f"`{tag}`" for tag in tg.suggested_tags]),
            ])
        
        lines.extend(["", report.summary])
    
    return "\n".join(lines)


# ============================================================
# CLI
# ============================================================

def main():
    lang = "zh" if "--zh" in sys.argv else "en"
    
    # DemoData
    listing = ListingInfo(
        title="Beautiful Handmade Bracelet",
        tags=["bracelet", "handmade", "gift", "jewelry", "beaded"],
        description="A beautiful handmade bracelet perfect for any occasion. Made with high quality beads.",
        category="jewelry",
        attributes={"material": "beads", "color": "blue"},
        images=5,
    )
    
    report = analyze_listing(listing)
    print(format_report(report, lang))


if __name__ == "__main__":
    main()