"""Shared provider-hidden search contract for API capabilities, CLI recipes, and docs."""

from __future__ import annotations

from copy import deepcopy
from typing import Any, Dict, Tuple


SEARCH_SCOPE = "search:run"


_SEARCH_ENDPOINTS: Dict[str, Dict[str, Any]] = {
    "search_companies": {
        "method": "POST",
        "path": "/api/search/companies",
        "required_scope": SEARCH_SCOPE,
        "body": {
            "query": "required free-text company search query",
            "limit": "optional 1-100 (default 25)",
        },
        "response": {"items_field": "items", "item_type": "company"},
    },
    "search_people": {
        "method": "POST",
        "path": "/api/search/people",
        "required_scope": SEARCH_SCOPE,
        "body": {
            "query": "optional free-text person/role query",
            "company": "optional target company name",
            "location": "optional location string",
            "skills": "optional string[]",
            "limit": "optional 1-100 (default 25)",
        },
        "response": {"items_field": "items", "item_type": "person"},
    },
    "search_similar_companies": {
        "method": "POST",
        "path": "/api/search/similar-companies",
        "required_scope": SEARCH_SCOPE,
        "body": {
            "company_name": "required seed company name",
            "company_domain": "optional official company domain",
            "company_description": "optional short semantic description to improve peer matching",
            "limit": "optional 1-100 (default 25)",
        },
        "response": {"items_field": "items", "item_type": "company"},
    },
    "search_news": {
        "method": "POST",
        "path": "/api/search/news",
        "required_scope": SEARCH_SCOPE,
        "body": {
            "query": "required free-text news query",
            "days_back": "optional lookback window in days (default 7)",
            "limit": "optional 1-100 (default 25)",
        },
        "response": {"items_field": "items", "item_type": "news_article"},
    },
    "search_local_businesses": {
        "method": "POST",
        "path": "/api/search/local-businesses",
        "required_scope": SEARCH_SCOPE,
        "body": {
            "query": "required local business query",
            "limit": "optional 1-100 (default 25)",
            "country": "optional country code (default us)",
            "language": "optional language code (default en)",
            "page": "optional page number (default 1)",
        },
        "response": {"items_field": "items", "item_type": "local_business"},
    },
    "search_reviews": {
        "method": "POST",
        "path": "/api/search/reviews",
        "required_scope": SEARCH_SCOPE,
        "body": {
            "cid": "optional listing CID",
            "place_id": "optional place identifier",
            "fid": "optional listing fid",
            "sort_by": "optional newest|relevance|rating (default newest)",
            "limit": "optional 1-100 (default 25)",
            "country": "optional country code (default us)",
            "language": "optional language code (default en)",
            "next_page_token": "optional pagination token",
            "page": "optional page number (default 1)",
        },
        "response": {"items_field": "items", "item_type": "review"},
    },
    "search_filings": {
        "method": "POST",
        "path": "/api/search/filings",
        "required_scope": SEARCH_SCOPE,
        "body": {
            "company_name": "required company name",
            "filing_types": "optional string[] (default ['10-K','10-Q'])",
        },
        "response": {"items_field": "items", "item_type": "filing"},
    },
}


_SEARCH_CAPABILITIES: Dict[str, Any] = {
    "surface_type": "provider_hidden_search",
    "connection_required": False,
    "requires_connected_account": False,
    "recommended_scope": SEARCH_SCOPE,
    "chooser_guidance": {
        "use_company_search_when": [
            "you need to discover target accounts before looking for contacts",
            "the search criteria are market, product, or industry driven",
        ],
        "use_people_search_when": [
            "you already know the target companies",
            "the search criteria are role, persona, or skill driven",
        ],
        "use_linkedin_instead_when": [
            "the source of truth is a LinkedIn or Sales Navigator search URL",
            "you need LinkedIn-native posts, comments, reactions, or engagement lists",
        ],
    },
    "pricing": {
        "charge_on": "actual_results_returned",
        "families": {
            "companies": {"credits_per_bucket": 1, "bucket_size": 10, "rule": "1 credit per 10 results"},
            "people": {"credits_per_bucket": 1, "bucket_size": 10, "rule": "1 credit per 10 results"},
            "similar_companies": {"credits_per_bucket": 1, "bucket_size": 10, "rule": "1 credit per 10 results"},
            "news": {"credits_per_bucket": 1, "bucket_size": 25, "rule": "1 credit per 25 results"},
            "local_businesses": {"credits_per_bucket": 1, "bucket_size": 25, "rule": "1 credit per 25 results"},
            "reviews": {"credits_per_bucket": 1, "bucket_size": 25, "rule": "1 credit per 25 results"},
            "filings": {"credits_per_bucket": 1, "bucket_size": 1, "rule": "1 credit per search"},
        },
    },
    "recommended_cli": [
        "autotouch search companies --query 'remote IT asset management' --limit 25",
        "autotouch search people --query 'VP IT' --company 'Rippling' --limit 25",
        "autotouch search recipe --type companies --out-file companies.json",
    ],
}


_SEARCH_RECIPES: Dict[str, Dict[str, Any]] = {
    "companies": {
        "payload": {"query": "remote IT asset management", "limit": 25},
        "usage": "autotouch search companies --data-file <payload.json>",
        "notes": [
            "Use this when you need to discover target accounts first.",
            "Pricing: 1 credit per 10 returned companies.",
        ],
    },
    "people": {
        "payload": {
            "query": "VP IT",
            "company": "Rippling",
            "location": "United States",
            "skills": ["endpoint management", "IT operations"],
            "limit": 25,
        },
        "usage": "autotouch search people --data-file <payload.json>",
        "notes": [
            "Use this when you already know the target companies or persona.",
            "Pricing: 1 credit per 10 returned people.",
        ],
    },
    "similar_companies": {
        "payload": {
            "company_name": "Rippling",
            "company_domain": "rippling.com",
            "company_description": "Workforce management and HR software platform for businesses",
            "limit": 25,
        },
        "usage": "autotouch search similar-companies --data-file <payload.json>",
        "notes": [
            "Good for expanding a seed account list.",
            "Best results come from providing company_domain and a short company_description when known.",
            "Pricing: 1 credit per 10 returned companies.",
        ],
    },
    "news": {
        "payload": {"query": "device management startups", "days_back": 14, "limit": 25},
        "usage": "autotouch search news --data-file <payload.json>",
        "notes": [
            "Use for recent intent signals and market monitoring.",
            "Pricing: 1 credit per 25 returned articles.",
        ],
    },
    "local_businesses": {
        "payload": {"query": "managed IT services austin texas", "limit": 25, "country": "us", "language": "en"},
        "usage": "autotouch search local-businesses --data-file <payload.json>",
        "notes": [
            "Best for local business or maps-style discovery.",
            "Pricing: 1 credit per 25 returned businesses.",
        ],
    },
    "reviews": {
        "payload": {"cid": "<GOOGLE_MAPS_CID>", "limit": 25, "sort_by": "newest"},
        "usage": "autotouch search reviews --data-file <payload.json>",
        "notes": [
            "Resolve the listing first from local-business search, then fetch reviews.",
            "Pricing: 1 credit per 25 returned reviews.",
        ],
    },
    "filings": {
        "payload": {"company_name": "Snowflake", "filing_types": ["10-K", "10-Q"]},
        "usage": "autotouch search filings --data-file <payload.json>",
        "notes": [
            "Use for public-company filings and SEC research.",
            "Pricing: 1 credit per successful search.",
        ],
    },
}


def search_endpoint_entries() -> Dict[str, Dict[str, Any]]:
    return deepcopy(_SEARCH_ENDPOINTS)


def search_capabilities_contract() -> Dict[str, Any]:
    return deepcopy(_SEARCH_CAPABILITIES)


def search_recipe_types() -> Tuple[str, ...]:
    return tuple(_SEARCH_RECIPES.keys())


def search_recipe_entries() -> Dict[str, Dict[str, Any]]:
    return deepcopy(_SEARCH_RECIPES)


def search_recipe_entry(recipe_type: str) -> Dict[str, Any] | None:
    recipe = _SEARCH_RECIPES.get(str(recipe_type or "").strip())
    return deepcopy(recipe) if isinstance(recipe, dict) else None


__all__ = [
    "SEARCH_SCOPE",
    "search_capabilities_contract",
    "search_endpoint_entries",
    "search_recipe_entries",
    "search_recipe_entry",
    "search_recipe_types",
]
