npmctl-namecheap 0.3.2__tar.gz

npmctl_namecheap-0.3.2/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: npmctl-namecheap
+Version: 0.3.2
+Summary: Namecheap DNS provider extension for npmctl.
+Author: npmctl contributors
+License-Expression: Apache-2.0
+Requires-Dist: requests>=2.32.0
+Requires-Python: >=3.10, <3.14
+Description-Content-Type: text/markdown
+
+# npmctl-namecheap
+
+Namecheap DNS provider extension for `npmctl`.
+
+Install the package beside `npmctl`, then inspect discovery with:
+
+```bash
+npmctl plugins list
+npmctl dns doctor --provider namecheap
+```
+
+Configuration is read from environment variables:
+
+- `NAMECHEAP_API_USER`
+- `NAMECHEAP_API_KEY`
+- `NAMECHEAP_USERNAME`
+- `NAMECHEAP_CLIENT_IP`
+- `NAMECHEAP_API_BASE_URL` for tests or non-default endpoints

npmctl_namecheap-0.3.2/README.md

@@ -0,0 +1,18 @@
+# npmctl-namecheap
+
+Namecheap DNS provider extension for `npmctl`.
+
+Install the package beside `npmctl`, then inspect discovery with:
+
+```bash
+npmctl plugins list
+npmctl dns doctor --provider namecheap
+```
+
+Configuration is read from environment variables:
+
+- `NAMECHEAP_API_USER`
+- `NAMECHEAP_API_KEY`
+- `NAMECHEAP_USERNAME`
+- `NAMECHEAP_CLIENT_IP`
+- `NAMECHEAP_API_BASE_URL` for tests or non-default endpoints

npmctl_namecheap-0.3.2/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "npmctl-namecheap"
+version = "0.3.2"
+description = "Namecheap DNS provider extension for npmctl."
+readme = "README.md"
+requires-python = ">=3.10,<3.14"
+license = "Apache-2.0"
+authors = [{ name = "npmctl contributors" }]
+dependencies = [
+  "requests>=2.32.0",
+]
+
+[project.entry-points."npmctl.dns_providers"]
+namecheap = "npmctl_namecheap.provider:NamecheapDnsProvider"
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.12"]
+build-backend = "uv_build"

npmctl_namecheap-0.3.2/src/npmctl_namecheap/__init__.py

@@ -0,0 +1,5 @@
+"""Namecheap DNS extension for npmctl."""
+
+from npmctl_namecheap.provider import NamecheapDnsProvider
+
+__all__ = ["NamecheapDnsProvider"]

npmctl_namecheap-0.3.2/src/npmctl_namecheap/client.py

@@ -0,0 +1,55 @@
+"""Small Namecheap XML API client."""
+
+from __future__ import annotations
+
+from typing import Any
+from xml.etree import ElementTree
+
+import requests
+
+from npmctl_namecheap.config import NamecheapConfig
+from npmctl_namecheap.errors import NamecheapError
+from npmctl_namecheap.models import NamecheapRecord, split_zone
+
+_NAMESPACE = {"nc": "http://api.namecheap.com/xml.response"}
+
+
+class NamecheapClient:
+    """HTTP client for the Namecheap XML API."""
+
+    def __init__(self, config: NamecheapConfig, *, timeout_s: float = 15.0) -> None:
+        self.config = config
+        self.timeout_s = timeout_s
+        self.session = requests.Session()
+
+    def zones(self) -> tuple[str, ...]:
+        data = self._request("namecheap.domains.getList")
+        domains = data.findall(".//nc:Domain", _NAMESPACE)
+        return tuple(sorted(str(item.attrib["Name"]).lower() for item in domains if item.attrib.get("Name")))
+
+    def records(self, zone: str) -> tuple[NamecheapRecord, ...]:
+        sld, tld = split_zone(zone)
+        data = self._request("namecheap.domains.dns.getHosts", SLD=sld, TLD=tld)
+        hosts = data.findall(".//nc:host", _NAMESPACE)
+        return tuple(NamecheapRecord.from_attrs(host.attrib) for host in hosts)
+
+    def _request(self, command: str, **params: str) -> ElementTree.Element:
+        query: dict[str, Any] = {
+            "ApiUser": self.config.api_user,
+            "ApiKey": self.config.api_key,
+            "UserName": self.config.username,
+            "ClientIp": self.config.client_ip,
+            "Command": command,
+            **params,
+        }
+        response = self.session.get(self.config.api_base_url, params=query, timeout=self.timeout_s)
+        if response.status_code < 200 or response.status_code >= 300:
+            raise NamecheapError(f"Namecheap API failed: HTTP {response.status_code}")
+        try:
+            parsed = ElementTree.fromstring(response.text)
+        except ElementTree.ParseError as exc:
+            raise NamecheapError("Namecheap API returned invalid XML") from exc
+        if parsed.attrib.get("Status") == "ERROR":
+            errors = [item.text or "unknown error" for item in parsed.findall(".//nc:Error", _NAMESPACE)]
+            raise NamecheapError("; ".join(errors))
+        return parsed

npmctl_namecheap-0.3.2/src/npmctl_namecheap/config.py

@@ -0,0 +1,47 @@
+"""Configuration loading for the Namecheap DNS provider."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Mapping
+
+
+@dataclass(frozen=True, slots=True)
+class NamecheapConfig:
+    """Namecheap API configuration."""
+
+    api_user: str
+    api_key: str
+    username: str
+    client_ip: str
+    api_base_url: str = "https://api.namecheap.com/xml.response"
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> NamecheapConfig:
+        values = os.environ if env is None else env
+        required = {
+            "api_user": values.get("NAMECHEAP_API_USER"),
+            "api_key": values.get("NAMECHEAP_API_KEY"),
+            "username": values.get("NAMECHEAP_USERNAME"),
+            "client_ip": values.get("NAMECHEAP_CLIENT_IP"),
+        }
+        missing = [name for name, value in required.items() if not value]
+        if missing:
+            raise ValueError(f"missing Namecheap config: {', '.join(missing)}")
+        return cls(
+            api_user=str(required["api_user"]),
+            api_key=str(required["api_key"]),
+            username=str(required["username"]),
+            client_ip=str(required["client_ip"]),
+            api_base_url=values.get("NAMECHEAP_API_BASE_URL", "https://api.namecheap.com/xml.response"),
+        )
+
+    def redacted(self) -> dict[str, str | bool]:
+        return {
+            "api_user": bool(self.api_user),
+            "api_key": bool(self.api_key),
+            "username": bool(self.username),
+            "client_ip": bool(self.client_ip),
+            "api_base_url": self.api_base_url,
+        }

npmctl_namecheap-0.3.2/src/npmctl_namecheap/errors.py

@@ -0,0 +1,7 @@
+"""Namecheap provider errors."""
+
+from __future__ import annotations
+
+
+class NamecheapError(RuntimeError):
+    """Raised when the Namecheap API returns an error."""

npmctl_namecheap-0.3.2/src/npmctl_namecheap/models.py

@@ -0,0 +1,60 @@
+"""Namecheap DNS response models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True, slots=True)
+class NamecheapRecord:
+    """One Namecheap host record."""
+
+    host_id: str | None
+    name: str
+    type: str
+    address: str
+    ttl: int | None = None
+    mx_pref: int | None = None
+
+    @classmethod
+    def from_attrs(cls, attrs: Mapping[str, Any]) -> NamecheapRecord:
+        ttl = _optional_int(attrs.get("TTL"))
+        mx_pref = _optional_int(attrs.get("MXPref"))
+        return cls(
+            host_id=_optional_str(attrs.get("HostId")),
+            name=str(attrs.get("Name", "")).lower(),
+            type=str(attrs.get("Type", "")).upper(),
+            address=str(attrs.get("Address", "")),
+            ttl=ttl,
+            mx_pref=mx_pref,
+        )
+
+    def to_dict(self) -> dict[str, str | int | None]:
+        return {
+            "id": self.host_id,
+            "name": self.name,
+            "type": self.type,
+            "value": self.address,
+            "ttl": self.ttl,
+            "priority": self.mx_pref,
+        }
+
+
+def split_zone(zone: str) -> tuple[str, str]:
+    labels = zone.strip().lower().rstrip(".").split(".")
+    if len(labels) < 2 or any(not label for label in labels):
+        raise ValueError("zone must be a domain such as example.com")
+    return ".".join(labels[:-1]), labels[-1]
+
+
+def _optional_int(value: Any) -> int | None:
+    if value in (None, ""):
+        return None
+    return int(value)
+
+
+def _optional_str(value: Any) -> str | None:
+    if value in (None, ""):
+        return None
+    return str(value)

npmctl_namecheap-0.3.2/src/npmctl_namecheap/provider.py

@@ -0,0 +1,27 @@
+"""npmctl DNS provider implementation for Namecheap."""
+
+from __future__ import annotations
+
+from npmctl_namecheap.client import NamecheapClient
+from npmctl_namecheap.config import NamecheapConfig
+
+
+class NamecheapDnsProvider:
+    """DNS provider backed by the Namecheap XML API."""
+
+    name = "namecheap"
+
+    def __init__(self, client: NamecheapClient | None = None) -> None:
+        self._client = client
+
+    @property
+    def client(self) -> NamecheapClient:
+        if self._client is None:
+            self._client = NamecheapClient(NamecheapConfig.from_env())
+        return self._client
+
+    def zones(self) -> tuple[str, ...]:
+        return self.client.zones()
+
+    def records(self, zone: str) -> tuple[dict[str, object], ...]:
+        return tuple(record.to_dict() for record in self.client.records(zone))

npmctl_namecheap-0.3.2/src/npmctl_namecheap/py.typed

@@ -0,0 +1 @@
+