hostinger-python-sdk 0.1.0__py3-none-any.whl

hostinger_sdk/models.py

@@ -0,0 +1,252 @@
+from __future__ import annotations
+
+import ipaddress
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Iterable, Optional, Union
+
+from .messages import text
+
+
+class RecordType(str, Enum):
+    A = "A"
+    AAAA = "AAAA"
+    ALIAS = "ALIAS"
+    CAA = "CAA"
+    CNAME = "CNAME"
+    MX = "MX"
+    NS = "NS"
+    SOA = "SOA"
+    SRV = "SRV"
+    TXT = "TXT"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+RecordTypeLike = Union[RecordType, str]
+
+
+def record_type(value: RecordTypeLike) -> str:
+    kind = value.value if isinstance(value, RecordType) else str(value).strip().upper()
+    if not kind:
+        raise ValueError(text("value.empty_type"))
+    return kind
+
+
+def hostname(value: str) -> str:
+    host = value.strip()
+    if host == "@" or host.endswith(".") or "." not in host:
+        return host
+    return f"{host}."
+
+
+def parse_datetime(value: Any) -> Optional[datetime]:
+    if not value or not isinstance(value, str):
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+@dataclass
+class DNSRecord:
+    type: str
+    name: str
+    data: str
+    ttl: Optional[int] = None
+    disabled: bool = field(default=False, compare=False)
+
+    def __post_init__(self) -> None:
+        self.type = record_type(self.type)
+        self.name = self.name.strip() or "@"
+
+    @classmethod
+    def a(cls, name: str, ip: str, ttl: Optional[int] = None) -> DNSRecord:
+        return cls("A", name, str(ipaddress.IPv4Address(ip)), ttl)
+
+    @classmethod
+    def aaaa(cls, name: str, ip: str, ttl: Optional[int] = None) -> DNSRecord:
+        return cls("AAAA", name, str(ipaddress.IPv6Address(ip)), ttl)
+
+    @classmethod
+    def cname(cls, name: str, target: str, ttl: Optional[int] = None) -> DNSRecord:
+        return cls("CNAME", name, hostname(target), ttl)
+
+    @classmethod
+    def alias(cls, name: str, target: str, ttl: Optional[int] = None) -> DNSRecord:
+        return cls("ALIAS", name, hostname(target), ttl)
+
+    @classmethod
+    def txt(cls, name: str, value: str, ttl: Optional[int] = None) -> DNSRecord:
+        return cls("TXT", name, value, ttl)
+
+    @classmethod
+    def mx(cls, name: str, host: str, priority: int = 10, ttl: Optional[int] = None) -> DNSRecord:
+        return cls("MX", name, f"{priority} {hostname(host)}", ttl)
+
+    @classmethod
+    def ns(cls, name: str, host: str, ttl: Optional[int] = None) -> DNSRecord:
+        return cls("NS", name, hostname(host), ttl)
+
+    @classmethod
+    def srv(
+        cls, name: str, target: str, port: int, priority: int = 10, weight: int = 5, ttl: Optional[int] = None
+    ) -> DNSRecord:
+        return cls("SRV", name, f"{priority} {weight} {port} {hostname(target)}", ttl)
+
+    @classmethod
+    def caa(cls, name: str, value: str, tag: str = "issue", flags: int = 0, ttl: Optional[int] = None) -> DNSRecord:
+        return cls("CAA", name, f'{flags} {tag} "{value}"', ttl)
+
+    def fqdn(self, domain: str) -> str:
+        return domain if self.name == "@" else f"{self.name}.{domain}"
+
+
+def records_from_zone(rows: Any) -> list[DNSRecord]:
+    found = []
+    for row in rows or []:
+        if not isinstance(row, dict):
+            continue
+        for item in row.get("records") or []:
+            if isinstance(item, dict):
+                found.append(DNSRecord(
+                    type=str(row.get("type", "")),
+                    name=str(row.get("name", "@")),
+                    data=str(item.get("content", "")),
+                    ttl=row.get("ttl"),
+                    disabled=bool(item.get("is_disabled", False)),
+                ))
+    return found
+
+
+def zone_from_records(records: Iterable[DNSRecord], default_ttl: int) -> list[dict[str, Any]]:
+    groups: dict[tuple[str, str], dict[str, Any]] = {}
+    for record in records:
+        key = (record.name, record.type)
+        group = groups.setdefault(key, {"name": record.name, "type": record.type, "ttl": None, "records": []})
+        if group["ttl"] is None and record.ttl is not None:
+            group["ttl"] = record.ttl
+        group["records"].append({"content": record.data})
+    for group in groups.values():
+        if group["ttl"] is None:
+            group["ttl"] = default_ttl
+    return list(groups.values())
+
+
+@dataclass
+class Snapshot:
+    id: int
+    reason: str
+    created_at: Optional[datetime] = None
+    records: list[DNSRecord] = field(default_factory=list)
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> Snapshot:
+        return cls(
+            id=int(data.get("id", 0)),
+            reason=str(data.get("reason", "")),
+            created_at=parse_datetime(data.get("created_at")),
+            records=records_from_zone(data.get("snapshot")),
+        )
+
+
+@dataclass
+class Domain:
+    domain: str
+    id: Optional[int] = None
+    type: str = ""
+    status: str = ""
+    created_at: Optional[datetime] = None
+    expires_at: Optional[datetime] = None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> Domain:
+        return cls(
+            domain=str(data.get("domain") or ""),
+            id=data.get("id"),
+            type=str(data.get("type", "")),
+            status=str(data.get("status", "")),
+            created_at=parse_datetime(data.get("created_at")),
+            expires_at=parse_datetime(data.get("expires_at")),
+        )
+
+
+@dataclass
+class DomainInfo:
+    domain: str
+    status: str = ""
+    message: Optional[str] = None
+    is_locked: bool = False
+    is_lockable: bool = False
+    is_privacy_protected: bool = False
+    is_privacy_protection_allowed: bool = False
+    name_servers: list[str] = field(default_factory=list)
+    child_name_servers: dict[str, list[str]] = field(default_factory=dict)
+    contacts: dict[str, int] = field(default_factory=dict)
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    registered_at: Optional[datetime] = None
+    expires_at: Optional[datetime] = None
+    transfer_lock_expires_at: Optional[datetime] = None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> DomainInfo:
+        servers = data.get("name_servers") or {}
+        names = [str(servers[key]) for key in sorted(servers) if servers[key]] if isinstance(servers, dict) else []
+        children = data.get("child_name_servers")
+        return cls(
+            domain=str(data.get("domain", "")),
+            status=str(data.get("status", "")),
+            message=data.get("message"),
+            is_locked=bool(data.get("is_locked", False)),
+            is_lockable=bool(data.get("is_lockable", False)),
+            is_privacy_protected=bool(data.get("is_privacy_protected", False)),
+            is_privacy_protection_allowed=bool(data.get("is_privacy_protection_allowed", False)),
+            name_servers=names,
+            child_name_servers=dict(children) if isinstance(children, dict) else {},
+            contacts=dict(data.get("domain_contacts") or {}),
+            created_at=parse_datetime(data.get("created_at")),
+            updated_at=parse_datetime(data.get("updated_at")),
+            registered_at=parse_datetime(data.get("registered_at")),
+            expires_at=parse_datetime(data.get("expires_at")),
+            transfer_lock_expires_at=parse_datetime(data.get("60_days_lock_expires_at")),
+        )
+
+
+@dataclass
+class Availability:
+    domain: str
+    available: bool
+    alternative: bool = False
+    restriction: Optional[str] = None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> Availability:
+        return cls(
+            domain=str(data.get("domain") or ""),
+            available=bool(data.get("is_available", False)),
+            alternative=bool(data.get("is_alternative", False)),
+            restriction=data.get("restriction"),
+        )
+
+
+@dataclass
+class Forwarding:
+    domain: str
+    redirect_type: str
+    redirect_url: str
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> Forwarding:
+        return cls(
+            domain=str(data.get("domain") or ""),
+            redirect_type=str(data.get("redirect_type", "")),
+            redirect_url=str(data.get("redirect_url", "")),
+            created_at=parse_datetime(data.get("created_at")),
+            updated_at=parse_datetime(data.get("updated_at")),
+        )

hostinger_sdk/resources/__init__.py

@@ -0,0 +1,4 @@
+from .dns import DNS, AsyncDNS, relative_name
+from .domains import AsyncDomains, Domains
+
+__all__ = ["DNS", "AsyncDNS", "Domains", "AsyncDomains", "relative_name"]

hostinger_sdk/resources/dns.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+import ipaddress
+from typing import Any, Iterable, Optional, Sequence, Union
+
+from .._base import Call, Flow
+from ..messages import text
+from ..models import (
+    DNSRecord,
+    RecordType,
+    RecordTypeLike,
+    Snapshot,
+    hostname,
+    record_type,
+    records_from_zone,
+    zone_from_records,
+)
+
+RecordValues = Union[str, DNSRecord, Iterable[Union[str, DNSRecord]]]
+HOST_TYPES = frozenset({"CNAME", "ALIAS", "NS"})
+
+
+def domain_name(value: str) -> str:
+    name = value.strip().lower().rstrip(".")
+    if not name:
+        raise ValueError(text("value.empty_domain"))
+    return name
+
+
+def relative_name(name: str, domain: str) -> str:
+    value = name.strip().lower()
+    if not value:
+        raise ValueError(text("value.empty_name"))
+    if value in ("@", domain, f"{domain}."):
+        return "@"
+    bare = value.rstrip(".")
+    if bare.endswith(f".{domain}"):
+        return bare[: -len(domain) - 1]
+    if value.endswith("."):
+        raise ValueError(text("value.foreign_name", name=name, domain=domain))
+    return value
+
+
+def ip_record_type(ip: str) -> RecordType:
+    return RecordType.A if ipaddress.ip_address(ip).version == 4 else RecordType.AAAA
+
+
+def _done(_: Any) -> None:
+    return None
+
+
+class DNS:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def _path(self, endpoint: str, **params: Any) -> str:
+        return self._client.settings.path(endpoint, **params)
+
+    def _zone_call(self, zone: str) -> Call:
+        return Call("GET", self._path("zone", domain=zone), parse=records_from_zone)
+
+    def _put_call(self, zone: str, records: Sequence[DNSRecord], overwrite: bool) -> Call:
+        body = {"overwrite": overwrite, "zone": zone_from_records(records, self._client.settings.default_ttl)}
+        return Call("PUT", self._path("zone", domain=zone), json=body, parse=_done)
+
+    def _delete_call(self, zone: str, pairs: Iterable[tuple[str, str]]) -> Call:
+        filters = [{"name": name, "type": kind} for kind, name in dict.fromkeys(pairs)]
+        return Call("DELETE", self._path("zone", domain=zone), json={"filters": filters}, parse=_done)
+
+    def _prepare(self, zone: str, records: Iterable[DNSRecord]) -> list[DNSRecord]:
+        prepared = []
+        for record in records:
+            copy = DNSRecord(record.type, relative_name(record.name, zone), record.data, record.ttl)
+            if copy.type in HOST_TYPES:
+                copy.data = hostname(copy.data)
+            prepared.append(copy)
+        return prepared
+
+    def list(self, domain: str, type: Optional[RecordTypeLike] = None, name: Optional[str] = None) -> Any:
+        zone = domain_name(domain)
+        kind = record_type(type) if type is not None else None
+        label = relative_name(name, zone) if name else None
+
+        def parse(body: Any) -> list[DNSRecord]:
+            return [r for r in records_from_zone(body)
+                    if (kind is None or r.type == kind) and (label is None or r.name == label)]
+
+        return self._client._execute(Call("GET", self._path("zone", domain=zone), parse=parse))
+
+    def exists(self, domain: str, type: RecordTypeLike, name: str) -> Any:
+        zone, kind, label = domain_name(domain), record_type(type), relative_name(name, domain_name(domain))
+        path = self._path("zone", domain=zone)
+        parse = lambda body: any(r.type == kind and r.name == label for r in records_from_zone(body))
+        return self._client._execute(Call("GET", path, parse=parse))
+
+    def add(self, domain: str, *records: DNSRecord) -> Any:
+        if not records:
+            raise ValueError(text("value.add_needs_records"))
+        zone = domain_name(domain)
+        return self._client._execute(self._put_call(zone, self._prepare(zone, records), overwrite=False))
+
+    def replace(
+        self, domain: str, type: RecordTypeLike, name: str, values: RecordValues, *, ttl: Optional[int] = None
+    ) -> Any:
+        zone, kind = domain_name(domain), record_type(type)
+        label = relative_name(name, zone)
+        if isinstance(values, (str, DNSRecord)):
+            values = [values]
+        wanted = [v if isinstance(v, DNSRecord) else DNSRecord(kind, label, str(v), ttl) for v in values]
+        if not wanted:
+            raise ValueError(text("value.no_values"))
+        for record in wanted:
+            record.type, record.name = kind, label
+            if record.ttl is None:
+                record.ttl = ttl
+        return self._client._execute(self._put_call(zone, self._prepare(zone, wanted), overwrite=True))
+
+    def replace_many(self, domain: str, records: Sequence[DNSRecord]) -> Any:
+        if not records:
+            raise ValueError(text("value.add_needs_records"))
+        zone = domain_name(domain)
+        return self._client._execute(self._put_call(zone, self._prepare(zone, records), overwrite=True))
+
+    def delete(self, domain: str, type: RecordTypeLike, name: str, data: Optional[str] = None) -> Any:
+        zone, kind = domain_name(domain), record_type(type)
+        label = relative_name(name, zone)
+        if data is None:
+            return self._client._execute(self._delete_call(zone, [(kind, label)]))
+
+        def flow() -> Flow[int]:
+            current = yield self._zone_call(zone)
+            group = [r for r in current if r.type == kind and r.name == label]
+            keep = [r for r in group if r.data != data and r.data.rstrip(".") != data.rstrip(".")]
+            if len(keep) == len(group):
+                return 0
+            if keep:
+                yield self._put_call(zone, keep, overwrite=True)
+            else:
+                yield self._delete_call(zone, [(kind, label)])
+            return len(group) - len(keep)
+
+        return self._client._drive(flow())
+
+    def delete_many(self, domain: str, pairs: Iterable[tuple[RecordTypeLike, str]]) -> Any:
+        zone = domain_name(domain)
+        cleaned = [(record_type(kind), relative_name(name, zone)) for kind, name in pairs]
+        return self._client._execute(self._delete_call(zone, cleaned))
+
+    def point(self, domain: str, name: str, ip: str, *, ttl: Optional[int] = None) -> Any:
+        address = str(ipaddress.ip_address(ip))
+        return self.replace(domain, ip_record_type(address), name, [address], ttl=ttl)
+
+    def unpoint(self, domain: str, name: str, ip_version: int = 4) -> Any:
+        return self.delete(domain, RecordType.A if ip_version == 4 else RecordType.AAAA, name)
+
+    def alias(self, domain: str, name: str, target: str, *, ttl: Optional[int] = None) -> Any:
+        return self.replace(domain, RecordType.CNAME, name, [target], ttl=ttl)
+
+    def set_txt(self, domain: str, name: str, values: Union[str, Iterable[str]], *, ttl: Optional[int] = None) -> Any:
+        return self.replace(domain, RecordType.TXT, name, values, ttl=ttl)
+
+    def validate(self, domain: str, records: Sequence[DNSRecord], *, overwrite: bool = True) -> Any:
+        zone = domain_name(domain)
+        body = {"overwrite": overwrite,
+                "zone": zone_from_records(self._prepare(zone, records), self._client.settings.default_ttl)}
+        return self._client._execute(Call("POST", self._path("zone_validate", domain=zone), json=body, parse=_done))
+
+    def reset(
+        self,
+        domain: str,
+        *,
+        reset_email_records: bool = True,
+        keep_types: Optional[Iterable[RecordTypeLike]] = None,
+        wait: bool = True,
+    ) -> Any:
+        body: dict[str, Any] = {"sync": wait, "reset_email_records": reset_email_records}
+        if keep_types:
+            body["whitelisted_record_types"] = [record_type(kind) for kind in keep_types]
+        path = self._path("zone_reset", domain=domain_name(domain))
+        return self._client._execute(Call("POST", path, json=body, parse=_done))
+
+    def snapshots(self, domain: str) -> Any:
+        parse = lambda body: [Snapshot.from_api(row) for row in body or [] if isinstance(row, dict)]
+        return self._client._execute(Call("GET", self._path("snapshots", domain=domain_name(domain)), parse=parse))
+
+    def snapshot(self, domain: str, snapshot_id: int) -> Any:
+        path = self._path("snapshot", domain=domain_name(domain), snapshot_id=int(snapshot_id))
+        return self._client._execute(Call("GET", path, parse=lambda body: Snapshot.from_api(body or {})))
+
+    def restore(self, domain: str, snapshot_id: int) -> Any:
+        path = self._path("snapshot_restore", domain=domain_name(domain), snapshot_id=int(snapshot_id))
+        return self._client._execute(Call("POST", path, parse=_done))
+
+
+class AsyncDNS(DNS):
+    pass

hostinger_sdk/resources/domains.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from .._base import Call, Flow
+from ..messages import text
+from ..models import Availability, Domain, DomainInfo, Forwarding
+from .dns import domain_name
+
+
+def _done(_: Any) -> None:
+    return None
+
+
+def _redirect(value: Any) -> str:
+    kind = str(value).strip()
+    if kind not in ("301", "302"):
+        raise ValueError(text("value.redirect_type", value=value))
+    return kind
+
+
+class Domains:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def _path(self, endpoint: str, **params: Any) -> str:
+        return self._client.settings.path(endpoint, **params)
+
+    def _run(self, call: Call) -> Any:
+        return self._client._execute(call)
+
+    def list(self) -> Any:
+        parse = lambda body: [Domain.from_api(row) for row in body or [] if isinstance(row, dict)]
+        return self._run(Call("GET", self._path("domains"), parse=parse))
+
+    def get(self, domain: str) -> Any:
+        path = self._path("domain", domain=domain_name(domain))
+        return self._run(Call("GET", path, parse=lambda body: DomainInfo.from_api(body or {})))
+
+    def available(self, name: str, tlds: Iterable[str], *, with_alternatives: bool = False) -> Any:
+        endings = [tld.strip().lstrip(".").lower() for tld in tlds if tld.strip()]
+        if not endings:
+            raise ValueError(text("value.no_tlds"))
+        body = {"domain": name.strip().lower(), "tlds": endings, "with_alternatives": with_alternatives}
+        parse = lambda rows: [Availability.from_api(row) for row in rows or [] if isinstance(row, dict)]
+        return self._run(Call("POST", self._path("availability"), json=body, parse=parse))
+
+    def set_nameservers(self, domain: str, servers: Iterable[str]) -> Any:
+        names = [server.strip().rstrip(".") for server in servers if server.strip()]
+        if not 2 <= len(names) <= 4:
+            raise ValueError(text("value.nameserver_count", count=len(names)))
+        body = {f"ns{index}": value for index, value in enumerate(names, start=1)}
+        return self._run(Call("PUT", self._path("nameservers", domain=domain_name(domain)), json=body, parse=_done))
+
+    def lock(self, domain: str) -> Any:
+        return self._run(Call("PUT", self._path("domain_lock", domain=domain_name(domain)), parse=_done))
+
+    def unlock(self, domain: str) -> Any:
+        return self._run(Call("DELETE", self._path("domain_lock", domain=domain_name(domain)), parse=_done))
+
+    def enable_privacy(self, domain: str) -> Any:
+        return self._run(Call("PUT", self._path("privacy", domain=domain_name(domain)), parse=_done))
+
+    def disable_privacy(self, domain: str) -> Any:
+        return self._run(Call("DELETE", self._path("privacy", domain=domain_name(domain)), parse=_done))
+
+    def forwarding(self, domain: str) -> Any:
+        path = self._path("forwarding", domain=domain_name(domain))
+        parse = lambda body: Forwarding.from_api(body) if isinstance(body, dict) else None
+        return self._run(Call("GET", path, parse=parse, allow_status=frozenset({404})))
+
+    def forward(self, domain: str, url: str, *, redirect_type: Any = 301) -> Any:
+        name, kind = domain_name(domain), _redirect(redirect_type)
+
+        def flow() -> Flow[Forwarding]:
+            path = self._path("forwarding", domain=name)
+            current = yield Call("GET", path, allow_status=frozenset({404}))
+            body = {"redirect_type": kind, "redirect_url": url}
+            if isinstance(current, dict) and current.get("redirect_url"):
+                result = yield Call("PUT", path, json=body)
+            else:
+                result = yield Call("POST", self._path("forwardings"), json={"domain": name, **body})
+            return Forwarding.from_api(result if isinstance(result, dict) else {"domain": name, **body})
+
+        return self._client._drive(flow())
+
+    def stop_forwarding(self, domain: str, *, missing_ok: bool = False) -> Any:
+        allow = frozenset({404}) if missing_ok else frozenset()
+        path = self._path("forwarding", domain=domain_name(domain))
+        return self._run(Call("DELETE", path, parse=_done, allow_status=allow))
+
+
+class AsyncDomains(Domains):
+    pass
+
+
+