domainhack 0.2.0__py3-none-any.whl

domainhack/usecases/brand_candidates.py

@@ -0,0 +1,195 @@
+"""Candidate domains for a brand name: the exact name, brand variants and domain hacks.
+
+``domainhack name sumanda`` checks three kinds of names:
+
+- EXACT: ``sumanda.<tld>`` for every requested TLD.
+- VARIANT (opt-in): ``get``/``use``/``try``/``hola``/``my`` + name and
+  name + ``hq``/``app``/``labs``/``studio``, only under ``.com`` plus the
+  first ``VARIANT_TLD_LIMIT`` other requested TLDs. That bounds variants to
+  9 x 4 = 36 names whatever the preset (``all-supported`` included).
+- HACK: (a) the name split at a known TLD it ends with (``plato`` ->
+  ``pla.to``); (b) the name plus a curated word whose ending is a known TLD
+  (``sumanda`` + ``studio`` -> ``sumandastud.io``). Hacks may use TLDs outside
+  the requested ones: finding them is the point.
+
+Every candidate goes through ``DomainHack.from_sld`` (label rules, IDN);
+invalid ones are counted in ``skipped``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from enum import Enum
+
+from domainhack.domain.entities import TLD, DomainHack, InvalidLabelError
+from domainhack.ports.known_tlds import KnownTlds
+
+VARIANT_PREFIXES: tuple[str, ...] = ("get", "use", "try", "hola", "my")
+VARIANT_SUFFIXES: tuple[str, ...] = ("hq", "app", "labs", "studio")
+# Variants are checked under .com plus this many other requested TLDs (in
+# request order, i.e. the preset's top ones).
+VARIANT_TLD_LIMIT = 3
+VARIANT_BASE_TLD = "com"
+
+# A preset whose value is this string expands to every TLD the catalog supports.
+CATALOG_PRESET = "catalog"
+
+Presets = Mapping[str, Sequence[str] | str]
+
+
+class CandidateKind(Enum):
+    EXACT = "exact"
+    VARIANT = "variant"
+    HACK = "hack"
+
+
+@dataclass(frozen=True)
+class HackWord:
+    """A word appended to the name to form a hack, with its short meaning."""
+
+    word: str
+    meaning: str
+
+
+@dataclass(frozen=True)
+class BrandCandidate:
+    """One name to check, why it is a candidate, and how a person would read it.
+
+    ``label`` is the human reading (``"sumanda studio"`` for ``sumandastud.io``);
+    ``meaning`` explains a hack word (empty otherwise).
+    """
+
+    domain: DomainHack
+    kind: CandidateKind
+    label: str
+    meaning: str = ""
+
+
+@dataclass(frozen=True)
+class TldSelection:
+    """``--tlds`` resolved: valid TLDs in request order, plus rejected suffixes."""
+
+    tlds: tuple[TLD, ...]
+    rejected: tuple[str, ...] = ()
+
+
+def resolve_tld_spec(
+    spec: str, presets: Presets, all_supported: Callable[[], Iterable[str]]
+) -> TldSelection:
+    """Expand ``"startup,com.ar,la"``: preset names and raw suffixes, mixed.
+
+    Order is preserved and duplicates dropped. Suffixes ``TLD`` rejects are
+    returned in ``rejected`` (the caller warns) instead of failing the run,
+    so presets may list suffixes this version cannot check yet; the catalog
+    preset drops them silently.
+    """
+    tlds: list[TLD] = []
+    rejected: list[str] = []
+    for raw in spec.split(","):
+        token = raw.strip().lstrip(".").lower()
+        if not token:
+            continue
+        preset = presets.get(token)
+        if preset is None:
+            suffixes: Iterable[str] = (token,)
+        elif preset == CATALOG_PRESET:
+            suffixes = sorted(all_supported())
+        else:
+            suffixes = preset
+        for suffix in suffixes:
+            try:
+                tld = TLD(suffix)
+            except ValueError:
+                # The catalog lists IDN TLDs (xn--...) nobody asked for by name.
+                if preset != CATALOG_PRESET and suffix not in rejected:
+                    rejected.append(suffix)
+                continue
+            if tld not in tlds:
+                tlds.append(tld)
+    return TldSelection(tuple(tlds), tuple(rejected))
+
+
+class BrandCandidates:
+    """Builds the candidate list for a name (see the module docstring).
+
+    ``execute`` returns candidates in check order: exact names (request
+    order), then hacks, then variants; each fqdn appears once (first kind
+    wins). After it runs, ``skipped`` counts invalid candidates,
+    ``suffix_hack_found`` says whether the name itself ends in a known TLD,
+    and ``unusable_suffixes`` lists known suffixes ``TLD`` cannot represent.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        tlds: Sequence[TLD],
+        known_tlds: KnownTlds,
+        *,
+        variants: bool = False,
+        hack_words: Sequence[HackWord] = (),
+    ) -> None:
+        self.name = DomainHack._normalize(name)
+        self._tlds = tuple(tlds)
+        self._known = known_tlds
+        self._variants = variants
+        self._hack_words = tuple(hack_words)
+        self.skipped = 0
+        self.suffix_hack_found = False
+        self.unusable_suffixes: list[str] = []
+
+    def execute(self) -> list[BrandCandidate]:
+        self.skipped = 0
+        self.suffix_hack_found = False
+        self.unusable_suffixes = []
+        seen: set[str] = set()
+        out: list[BrandCandidate] = []
+        for sld, tld, kind, label, meaning in self._raw():
+            try:
+                domain = DomainHack.from_sld(sld, tld)
+            except InvalidLabelError:
+                self.skipped += 1
+                continue
+            if domain.fqdn in seen:
+                continue
+            seen.add(domain.fqdn)
+            out.append(BrandCandidate(domain, kind, label, meaning))
+        return out
+
+    def _raw(self) -> Iterable[tuple[str, TLD, CandidateKind, str, str]]:
+        name = self.name
+        for tld in self._tlds:
+            yield name, tld, CandidateKind.EXACT, name, ""
+        for sld, tld in self._split(name, min_tail=0):
+            self.suffix_hack_found = True
+            yield sld, tld, CandidateKind.HACK, name, ""
+        for hw in self._hack_words:
+            # The TLD must lie within the extra word, so the name stays whole.
+            for sld, tld in self._split(name + hw.word, min_tail=len(hw.word)):
+                yield sld, tld, CandidateKind.HACK, f"{name} {hw.word}", hw.meaning
+        if self._variants:
+            for tld in self._variant_tlds():
+                for prefix in VARIANT_PREFIXES:
+                    yield prefix + name, tld, CandidateKind.VARIANT, f"{prefix} {name}", ""
+                for suffix in VARIANT_SUFFIXES:
+                    yield name + suffix, tld, CandidateKind.VARIANT, f"{name} {suffix}", ""
+
+    def _split(self, text: str, *, min_tail: int) -> Iterable[tuple[str, TLD]]:
+        """(sld, tld) for each known suffix of ``text`` that fits in its last ``min_tail``
+        characters (any length when 0)."""
+        for suffix in self._known.suffixes_of(text):
+            letters = len(suffix.replace(".", ""))
+            if min_tail and letters > min_tail:
+                continue
+            try:
+                tld = TLD(suffix)
+            except ValueError:
+                if suffix not in self.unusable_suffixes:
+                    self.unusable_suffixes.append(suffix)
+                continue
+            yield text[:-letters], tld
+
+    def _variant_tlds(self) -> list[TLD]:
+        base = TLD(VARIANT_BASE_TLD)
+        others = [t for t in self._tlds if t != base][:VARIANT_TLD_LIMIT]
+        return [base, *others]

domainhack/usecases/brand_report.py

@@ -0,0 +1,271 @@
+"""Turn the check results for a brand name into a structured report with a recommendation.
+
+Sections (every list is in candidate order, so the report does not depend on
+the order checks completed in):
+
+- ``exact``: ``name.<tld>`` for each requested TLD, whatever its status;
+- ``variants``: available brand variants (``getsumanda.com``...);
+- ``hacks``: every hack candidate, whatever its status;
+- ``taken``: every taken name, with its registration details;
+- ``unverifiable``: names that could not be checked (registry error or
+  unreachable, no registrar for the TLD, run interrupted), each with the reason;
+- ``dns_conflicts``: registry says available, DNS says delegated.
+
+Recommendation score (higher is better)::
+
+    score = tier * 100 - len(name)
+
+    tier  100  exact name under .com
+           90  exact name under a strong TLD (.app .io .ai .co)
+           70  exact name under any other TLD
+           60  brand variant under .com (getsumanda.com)
+           50  hack that spells the name itself (plato -> pla.to)
+           45  brand variant under another TLD
+           40  hack with an extra word (sumandastud.io)
+
+The tier always decides; length (of the name as displayed) only breaks ties
+within a tier, then alphabetical order. Only AVAILABLE names without a DNS
+conflict are recommended: taken, dropping, DNS-conflict and unverifiable names
+never are. Advice lines mention a taken exact ``.com`` (with its parking
+service, if any) and dropping names.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection, Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from enum import Enum
+
+from domainhack.domain.entities import TLD, Availability, DomainCheckResult
+from domainhack.usecases.brand_candidates import BrandCandidate, CandidateKind
+
+STRONG_TLDS: frozenset[str] = frozenset({"app", "io", "ai", "co"})
+RECOMMENDATION_LIMIT = 5
+
+TIER_EXACT_COM = 100
+TIER_EXACT_STRONG = 90
+TIER_EXACT_OTHER = 70
+TIER_VARIANT_COM = 60
+TIER_HACK_NAME = 50
+TIER_VARIANT_OTHER = 45
+TIER_HACK_WORD = 40
+
+
+class EntryStatus(Enum):
+    AVAILABLE = "available"
+    TAKEN = "taken"
+    DROPPING = "dropping"
+    DNS_CONFLICT = "dns-conflict"
+    ERROR = "error"
+    UNSUPPORTED = "unsupported"
+    NOT_CHECKED = "not-checked"
+
+
+_UNVERIFIABLE = frozenset({EntryStatus.ERROR, EntryStatus.UNSUPPORTED, EntryStatus.NOT_CHECKED})
+
+
+@dataclass(frozen=True)
+class ReportEntry:
+    """One candidate with its outcome and a one-line human ``detail``."""
+
+    candidate: BrandCandidate
+    status: EntryStatus
+    detail: str = ""
+    result: DomainCheckResult | None = None
+
+    @property
+    def name(self) -> str:
+        return self.candidate.domain.display
+
+    @property
+    def fqdn(self) -> str:
+        return self.candidate.domain.fqdn
+
+    @property
+    def kind(self) -> CandidateKind:
+        return self.candidate.kind
+
+    @property
+    def label(self) -> str:
+        return self.candidate.label
+
+
+@dataclass(frozen=True)
+class Recommendation:
+    rank: int
+    entry: ReportEntry
+    score: int
+    reason: str
+
+
+@dataclass(frozen=True)
+class BrandReport:
+    name: str
+    tlds: tuple[TLD, ...]
+    exact: tuple[ReportEntry, ...]
+    variants: tuple[ReportEntry, ...]
+    variants_requested: bool
+    hacks: tuple[ReportEntry, ...]
+    suffix_hack_found: bool
+    taken: tuple[ReportEntry, ...]
+    unverifiable: tuple[ReportEntry, ...]
+    dns_conflicts: tuple[ReportEntry, ...]
+    recommendations: tuple[Recommendation, ...]
+    more_available: int  # available names beyond RECOMMENDATION_LIMIT
+    advice: tuple[str, ...]
+    notes: tuple[str, ...]
+
+    @property
+    def no_suffix_hack_note(self) -> str:
+        return f"no TLD is a suffix of {self.name!r}"
+
+
+def _date(result: DomainCheckResult, attr: str) -> str:
+    value = getattr(result, attr)
+    return value.date().isoformat() if value is not None else ""
+
+
+def _taken_detail(result: DomainCheckResult) -> str:
+    parts: list[str] = []
+    if since := _date(result, "registered_at"):
+        parts.append(f"since {since}")
+    if expires := _date(result, "expires_at"):
+        parts.append(f"expires {expires}")
+    if result.registrar:
+        parts.append(f"registrar {result.registrar}")
+    if result.parked_hint:
+        parts.append(f"parked: {result.parked_hint}")
+    if result.is_dropping:
+        parts.append(f"dropping: {', '.join(result.dropping_statuses)}")
+    if result.dns is not None and not result.dns.error and not result.dns.is_delegated:
+        parts.append("no DNS delegation")
+    return ", ".join(parts)
+
+
+def _classify(candidate: BrandCandidate, result: DomainCheckResult | None, why: str) -> ReportEntry:
+    if result is None:
+        status = EntryStatus.UNSUPPORTED if why else EntryStatus.NOT_CHECKED
+        return ReportEntry(candidate, status, why or "not checked (run interrupted)")
+    if result.availability is Availability.ERROR:
+        return ReportEntry(
+            candidate, EntryStatus.ERROR, result.error_message or "check failed", result
+        )
+    if result.availability is Availability.TAKEN:
+        status = EntryStatus.DROPPING if result.is_dropping else EntryStatus.TAKEN
+        return ReportEntry(candidate, status, _taken_detail(result), result)
+    dns = result.dns
+    if result.dns_conflict:
+        assert dns is not None
+        ns = ", ".join(dns.nameservers)
+        detail = f"registry says available, but DNS delegates it to {ns}"
+        return ReportEntry(candidate, EntryStatus.DNS_CONFLICT, detail, result)
+    if dns is None:
+        detail = ""
+    elif dns.error:
+        detail = f"DNS lookup failed: {dns.error}"
+    else:
+        detail = "DNS: not delegated"
+    return ReportEntry(candidate, EntryStatus.AVAILABLE, detail, result)
+
+
+def _tier(entry: ReportEntry) -> tuple[int, str]:
+    tld = entry.candidate.domain.tld.suffix
+    match entry.kind:
+        case CandidateKind.EXACT:
+            if tld == "com":
+                return TIER_EXACT_COM, "exact name, .com"
+            if tld in STRONG_TLDS:
+                return TIER_EXACT_STRONG, f"exact name, strong TLD .{tld}"
+            return TIER_EXACT_OTHER, f"exact name, .{tld}"
+        case CandidateKind.VARIANT:
+            if tld == "com":
+                return TIER_VARIANT_COM, f"brand variant on .com ({entry.label})"
+            return TIER_VARIANT_OTHER, f"brand variant ({entry.label})"
+        case CandidateKind.HACK:
+            domain = entry.candidate.domain
+            if domain.sld + tld.replace(".", "") == entry.label:
+                return TIER_HACK_NAME, "domain hack spelling the name"
+            return TIER_HACK_WORD, f"domain hack ({entry.label})"
+    raise AssertionError(entry.kind)  # pragma: no cover
+
+
+def score(entry: ReportEntry) -> int:
+    """``tier * 100 - len(name)``; see the module docstring."""
+    return _tier(entry)[0] * 100 - len(entry.name)
+
+
+def _advice(entries: Sequence[ReportEntry]) -> list[str]:
+    lines: list[str] = []
+    for entry in entries:
+        result = entry.result
+        if result is None or result.availability is not Availability.TAKEN:
+            continue
+        exact_com = entry.kind is CandidateKind.EXACT and entry.candidate.domain.tld.suffix == "com"
+        if entry.status is EntryStatus.DROPPING:
+            lines.append(
+                f"{entry.name} is dropping ({', '.join(result.dropping_statuses)}): it may be "
+                "free soon, but cannot be registered yet"
+            )
+        elif exact_com:
+            line = f"{entry.name} is taken"
+            if expires := _date(result, "expires_at"):
+                line += f" (expires {expires})"
+            if result.parked_hint:
+                line += f"; parked at {result.parked_hint}: may be purchasable from the owner"
+            lines.append(line)
+    return lines
+
+
+def build_brand_report(
+    name: str,
+    candidates: Sequence[BrandCandidate],
+    results: Iterable[DomainCheckResult],
+    *,
+    tlds: Sequence[TLD],
+    suffix_hack_found: bool,
+    variants_requested: bool,
+    unsupported: Collection[TLD] = (),
+    notes: Sequence[str] = (),
+    unsupported_reasons: Mapping[TLD, str] | None = None,
+) -> BrandReport:
+    """Build the report. Candidates without a result are unverifiable: "no registrar
+    supports .x" when their TLD is in ``unsupported`` (or the message given for it
+    in ``unsupported_reasons``, which explains why), otherwise "not checked"."""
+    reasons = unsupported_reasons or {}
+    by_fqdn = {r.domain.fqdn: r for r in results}
+    entries = [
+        _classify(
+            c,
+            by_fqdn.get(c.domain.fqdn),
+            (reasons.get(c.domain.tld) or f"no registrar supports .{c.domain.tld.suffix}")
+            if c.domain.tld in unsupported
+            else "",
+        )
+        for c in candidates
+    ]
+
+    def of(kind: CandidateKind) -> list[ReportEntry]:
+        return [e for e in entries if e.kind is kind]
+
+    available = [e for e in entries if e.status is EntryStatus.AVAILABLE]
+    ranked = sorted(available, key=lambda e: (-score(e), e.name))
+    recommendations = tuple(
+        Recommendation(i, e, score(e), _tier(e)[1])
+        for i, e in enumerate(ranked[:RECOMMENDATION_LIMIT], start=1)
+    )
+    return BrandReport(
+        name=name,
+        tlds=tuple(tlds),
+        exact=tuple(of(CandidateKind.EXACT)),
+        variants=tuple(e for e in of(CandidateKind.VARIANT) if e.status is EntryStatus.AVAILABLE),
+        variants_requested=variants_requested,
+        hacks=tuple(of(CandidateKind.HACK)),
+        suffix_hack_found=suffix_hack_found,
+        taken=tuple(e for e in entries if e.status in (EntryStatus.TAKEN, EntryStatus.DROPPING)),
+        unverifiable=tuple(e for e in entries if e.status in _UNVERIFIABLE),
+        dns_conflicts=tuple(e for e in entries if e.status is EntryStatus.DNS_CONFLICT),
+        recommendations=recommendations,
+        more_available=max(0, len(ranked) - RECOMMENDATION_LIMIT),
+        advice=tuple(_advice(entries)),
+        notes=tuple(notes),
+    )