npmctl-cloudflare 0.3.6__tar.gz

npmctl_cloudflare-0.3.6/LICENSE

@@ -0,0 +1 @@
+Apache-2.0

npmctl_cloudflare-0.3.6/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: npmctl-cloudflare
+Version: 0.3.6
+Summary: Cloudflare DNS provider extension for npmctl.
+Keywords: cloudflare,dns,nginx-proxy-manager,npmctl
+Author: Jacob Stewart
+Author-email: Jacob Stewart <jacob@swarmauri.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: Name Service (DNS)
+Classifier: Topic :: System :: Systems Administration
+Requires-Dist: requests>=2.32.0
+Requires-Python: >=3.10, <3.15
+Project-URL: Homepage, https://github.com/groupsum/npmctl
+Project-URL: Repository, https://github.com/groupsum/npmctl
+Project-URL: Documentation, https://github.com/groupsum/npmctl/tree/master/packages/npmctl-cloudflare
+Project-URL: Issues, https://github.com/groupsum/npmctl/issues
+Description-Content-Type: text/markdown
+
+<h1 align="center">npmctl-cloudflare</h1>
+
+<p align="center"><strong>Cloudflare DNS provider plugin for npmctl</strong></p>
+
+<p align="center">
+  Extend <code>npmctl</code> with Cloudflare-backed DNS record management for declarative workflows, provider discovery, and DNS-aware automation.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/npmctl-cloudflare/"><img src="https://img.shields.io/pypi/v/npmctl-cloudflare.svg" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/npmctl-cloudflare/"><img src="https://img.shields.io/pypi/pyversions/npmctl-cloudflare.svg" alt="Python versions"></a>
+  <a href="https://github.com/groupsum/npmctl/actions/workflows/ci.yml"><img src="https://github.com/groupsum/npmctl/actions/workflows/ci.yml/badge.svg?branch=master" alt="CI"></a>
+  <a href="https://github.com/groupsum/npmctl/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="Apache 2.0 License"></a>
+</p>
+
+<p align="center">
+  <a href="https://hits.sh/github.com/groupsum/npmctl/blob/master/packages/npmctl-cloudflare/README.md/"><img src="https://hits.sh/github.com/groupsum/npmctl/blob/master/packages/npmctl-cloudflare/README.md.svg?label=npmctl-cloudflare%20package%20hits" alt="npmctl-cloudflare package hits"></a>
+  <a href="https://pepy.tech/projects/npmctl-cloudflare"><img src="https://static.pepy.tech/badge/npmctl-cloudflare" alt="npmctl-cloudflare downloads"></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/groupsum/npmctl/master/docs/images/marketing/npmctl-architecture-infographic.png" alt="npmctl architecture infographic">
+</p>
+
+`npmctl-cloudflare` is the Cloudflare DNS provider package for `npmctl`. Install it when you want desired-state DNS records or DNS diagnostics to resolve through Cloudflare instead of using only the base `npmctl` package.
+
+## Supported Python Versions
+
+`npmctl-cloudflare` supports Python `3.10`, `3.11`, `3.12`, `3.13`, and `3.14`.
+
+## Why npmctl-cloudflare
+
+- Adds Cloudflare DNS provider discovery to `npmctl`
+- Lets DNS workflows live beside proxy and certificate desired state
+- Keeps Cloudflare API tokens out of the core CLI package
+- Supports operator diagnostics through `npmctl dns doctor`
+- Provides client helpers for Cloudflare A and CNAME record workflows
+
+## FAQ
+
+### What is npmctl-cloudflare?
+
+**Answer:** `npmctl-cloudflare` is a plugin package that teaches `npmctl` how to talk to the Cloudflare DNS Records API for DNS record operations and DNS provider diagnostics.
+
+### When do I need npmctl-cloudflare?
+
+**Answer:** You need `npmctl-cloudflare` when your `npmctl` workflow includes Cloudflare-managed DNS records or when you want `npmctl` to validate Cloudflare DNS connectivity and credentials.
+
+### Does npmctl-cloudflare work without npmctl?
+
+**Answer:** No. `npmctl-cloudflare` is an extension package for `npmctl`, not a standalone CLI.
+
+### Can npmctl-cloudflare set A and CNAME records?
+
+**Answer:** Yes. The Cloudflare DNS Records API supports A and CNAME records, and this package exposes helpers for create, replace, patch, and delete operations.
+
+### What credentials are required?
+
+**Answer:** Cloudflare API access requires `CLOUDFLARE_API_TOKEN`. For diagnostics, grant zone read and DNS read access. For record changes, grant DNS write access to the target zone.
+
+## Install
+
+Install the base CLI and the Cloudflare provider package together:
+
+```bash
+pipx install npmctl
+pipx inject npmctl npmctl-cloudflare
+npmctl plugins list
+```
+
+With `uv`:
+
+```bash
+uv tool install npmctl
+uv tool install npmctl-cloudflare
+npmctl plugins list
+```
+
+Inside a virtual environment:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install npmctl npmctl-cloudflare
+npmctl plugins list
+```
+
+## Configure Cloudflare
+
+Set the required environment variable:
+
+```bash
+export CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
+```
+
+Optional for tests, proxies, or alternate endpoints:
+
+```bash
+export CLOUDFLARE_API_BASE_URL=https://api.cloudflare.com/client/v4
+```
+
+## Verify Plugin Discovery
+
+Check that `npmctl` can discover the provider:
+
+```bash
+npmctl plugins list
+npmctl dns doctor --provider cloudflare
+```
+
+## Minimal DNS Workflow
+
+Once the provider is installed and configured, `npmctl` can validate or diagnose Cloudflare-backed DNS behavior through the base CLI:
+
+```bash
+npmctl dns providers
+npmctl dns zones --provider cloudflare
+npmctl dns records --provider cloudflare --zone example.com
+```
+
+## Cloudflare API Surface
+
+The provider follows the Cloudflare DNS Records API:
+
+- `GET /zones`: discover zones available to the token.
+- `GET /zones/{zone_id}/dns_records`: list DNS records in one zone.
+- `POST /zones/{zone_id}/dns_records`: create A, CNAME, and other supported records.
+- `PUT /zones/{zone_id}/dns_records/{dns_record_id}`: overwrite an existing record.
+- `PATCH /zones/{zone_id}/dns_records/{dns_record_id}`: partially update an existing record.
+- `DELETE /zones/{zone_id}/dns_records/{dns_record_id}`: delete a record.
+
+## Programmatic Record Operations
+
+The npmctl DNS provider contract requires `zones()` and `records(zone)`. This package also exposes client helpers for API-backed record mutation:
+
+```python
+from npmctl_cloudflare import CloudflareClient, CloudflareConfig
+
+client = CloudflareClient(CloudflareConfig.from_env())
+record = client.create_record("example.com", type="A", name="www", value="192.0.2.10", ttl=300)
+client.patch_record("example.com", str(record.record_id), value="192.0.2.11")
+client.delete_record("example.com", str(record.record_id))
+```
+
+CNAME creation uses the same method:
+
+```python
+client.create_record("example.com", type="CNAME", name="app", value="target.example.net", ttl=300)
+```
+
+## Safety Notes
+
+- Only operate on zones that are authoritative in Cloudflare.
+- Use least-privilege API tokens scoped to the intended zone.
+- Keep `CLOUDFLARE_API_TOKEN` out of desired-state files and logs.
+- Cloudflare prevents CNAME records from coexisting with A or AAAA records on the same name.
+- Use npmctl owner metadata for desired DNS records so future apply support can remain owner-scoped.
+
+## More Documentation
+
+- Related PyPI package: https://pypi.org/project/npmctl/
+- Repository: https://github.com/groupsum/npmctl
+- DNS provider docs: https://github.com/groupsum/npmctl/tree/master/docs/dns-providers.md

npmctl_cloudflare-0.3.6/README.md

@@ -0,0 +1,163 @@
+<h1 align="center">npmctl-cloudflare</h1>
+
+<p align="center"><strong>Cloudflare DNS provider plugin for npmctl</strong></p>
+
+<p align="center">
+  Extend <code>npmctl</code> with Cloudflare-backed DNS record management for declarative workflows, provider discovery, and DNS-aware automation.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/npmctl-cloudflare/"><img src="https://img.shields.io/pypi/v/npmctl-cloudflare.svg" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/npmctl-cloudflare/"><img src="https://img.shields.io/pypi/pyversions/npmctl-cloudflare.svg" alt="Python versions"></a>
+  <a href="https://github.com/groupsum/npmctl/actions/workflows/ci.yml"><img src="https://github.com/groupsum/npmctl/actions/workflows/ci.yml/badge.svg?branch=master" alt="CI"></a>
+  <a href="https://github.com/groupsum/npmctl/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="Apache 2.0 License"></a>
+</p>
+
+<p align="center">
+  <a href="https://hits.sh/github.com/groupsum/npmctl/blob/master/packages/npmctl-cloudflare/README.md/"><img src="https://hits.sh/github.com/groupsum/npmctl/blob/master/packages/npmctl-cloudflare/README.md.svg?label=npmctl-cloudflare%20package%20hits" alt="npmctl-cloudflare package hits"></a>
+  <a href="https://pepy.tech/projects/npmctl-cloudflare"><img src="https://static.pepy.tech/badge/npmctl-cloudflare" alt="npmctl-cloudflare downloads"></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/groupsum/npmctl/master/docs/images/marketing/npmctl-architecture-infographic.png" alt="npmctl architecture infographic">
+</p>
+
+`npmctl-cloudflare` is the Cloudflare DNS provider package for `npmctl`. Install it when you want desired-state DNS records or DNS diagnostics to resolve through Cloudflare instead of using only the base `npmctl` package.
+
+## Supported Python Versions
+
+`npmctl-cloudflare` supports Python `3.10`, `3.11`, `3.12`, `3.13`, and `3.14`.
+
+## Why npmctl-cloudflare
+
+- Adds Cloudflare DNS provider discovery to `npmctl`
+- Lets DNS workflows live beside proxy and certificate desired state
+- Keeps Cloudflare API tokens out of the core CLI package
+- Supports operator diagnostics through `npmctl dns doctor`
+- Provides client helpers for Cloudflare A and CNAME record workflows
+
+## FAQ
+
+### What is npmctl-cloudflare?
+
+**Answer:** `npmctl-cloudflare` is a plugin package that teaches `npmctl` how to talk to the Cloudflare DNS Records API for DNS record operations and DNS provider diagnostics.
+
+### When do I need npmctl-cloudflare?
+
+**Answer:** You need `npmctl-cloudflare` when your `npmctl` workflow includes Cloudflare-managed DNS records or when you want `npmctl` to validate Cloudflare DNS connectivity and credentials.
+
+### Does npmctl-cloudflare work without npmctl?
+
+**Answer:** No. `npmctl-cloudflare` is an extension package for `npmctl`, not a standalone CLI.
+
+### Can npmctl-cloudflare set A and CNAME records?
+
+**Answer:** Yes. The Cloudflare DNS Records API supports A and CNAME records, and this package exposes helpers for create, replace, patch, and delete operations.
+
+### What credentials are required?
+
+**Answer:** Cloudflare API access requires `CLOUDFLARE_API_TOKEN`. For diagnostics, grant zone read and DNS read access. For record changes, grant DNS write access to the target zone.
+
+## Install
+
+Install the base CLI and the Cloudflare provider package together:
+
+```bash
+pipx install npmctl
+pipx inject npmctl npmctl-cloudflare
+npmctl plugins list
+```
+
+With `uv`:
+
+```bash
+uv tool install npmctl
+uv tool install npmctl-cloudflare
+npmctl plugins list
+```
+
+Inside a virtual environment:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install npmctl npmctl-cloudflare
+npmctl plugins list
+```
+
+## Configure Cloudflare
+
+Set the required environment variable:
+
+```bash
+export CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
+```
+
+Optional for tests, proxies, or alternate endpoints:
+
+```bash
+export CLOUDFLARE_API_BASE_URL=https://api.cloudflare.com/client/v4
+```
+
+## Verify Plugin Discovery
+
+Check that `npmctl` can discover the provider:
+
+```bash
+npmctl plugins list
+npmctl dns doctor --provider cloudflare
+```
+
+## Minimal DNS Workflow
+
+Once the provider is installed and configured, `npmctl` can validate or diagnose Cloudflare-backed DNS behavior through the base CLI:
+
+```bash
+npmctl dns providers
+npmctl dns zones --provider cloudflare
+npmctl dns records --provider cloudflare --zone example.com
+```
+
+## Cloudflare API Surface
+
+The provider follows the Cloudflare DNS Records API:
+
+- `GET /zones`: discover zones available to the token.
+- `GET /zones/{zone_id}/dns_records`: list DNS records in one zone.
+- `POST /zones/{zone_id}/dns_records`: create A, CNAME, and other supported records.
+- `PUT /zones/{zone_id}/dns_records/{dns_record_id}`: overwrite an existing record.
+- `PATCH /zones/{zone_id}/dns_records/{dns_record_id}`: partially update an existing record.
+- `DELETE /zones/{zone_id}/dns_records/{dns_record_id}`: delete a record.
+
+## Programmatic Record Operations
+
+The npmctl DNS provider contract requires `zones()` and `records(zone)`. This package also exposes client helpers for API-backed record mutation:
+
+```python
+from npmctl_cloudflare import CloudflareClient, CloudflareConfig
+
+client = CloudflareClient(CloudflareConfig.from_env())
+record = client.create_record("example.com", type="A", name="www", value="192.0.2.10", ttl=300)
+client.patch_record("example.com", str(record.record_id), value="192.0.2.11")
+client.delete_record("example.com", str(record.record_id))
+```
+
+CNAME creation uses the same method:
+
+```python
+client.create_record("example.com", type="CNAME", name="app", value="target.example.net", ttl=300)
+```
+
+## Safety Notes
+
+- Only operate on zones that are authoritative in Cloudflare.
+- Use least-privilege API tokens scoped to the intended zone.
+- Keep `CLOUDFLARE_API_TOKEN` out of desired-state files and logs.
+- Cloudflare prevents CNAME records from coexisting with A or AAAA records on the same name.
+- Use npmctl owner metadata for desired DNS records so future apply support can remain owner-scoped.
+
+## More Documentation
+
+- Related PyPI package: https://pypi.org/project/npmctl/
+- Repository: https://github.com/groupsum/npmctl
+- DNS provider docs: https://github.com/groupsum/npmctl/tree/master/docs/dns-providers.md

npmctl_cloudflare-0.3.6/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "npmctl-cloudflare"
+version = "0.3.6"
+description = "Cloudflare DNS provider extension for npmctl."
+readme = "README.md"
+requires-python = ">=3.10,<3.15"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Jacob Stewart", email = "jacob@swarmauri.com" }]
+classifiers = [
+  "Development Status :: 1 - Planning",
+  "Intended Audience :: System Administrators",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Internet :: Name Service (DNS)",
+  "Topic :: System :: Systems Administration",
+]
+keywords = ["cloudflare", "dns", "nginx-proxy-manager", "npmctl"]
+dependencies = [
+  "requests>=2.32.0",
+]
+
+[project.entry-points."npmctl.dns_providers"]
+cloudflare = "npmctl_cloudflare.provider:CloudflareDnsProvider"
+
+[project.urls]
+Homepage = "https://github.com/groupsum/npmctl"
+Repository = "https://github.com/groupsum/npmctl"
+Documentation = "https://github.com/groupsum/npmctl/tree/master/packages/npmctl-cloudflare"
+Issues = "https://github.com/groupsum/npmctl/issues"
+
+[build-system]
+requires = ["uv-build>=0.11.8,<0.12"]
+build-backend = "uv_build"

npmctl_cloudflare-0.3.6/src/npmctl_cloudflare/__init__.py

@@ -0,0 +1,7 @@
+"""Cloudflare DNS extension for npmctl."""
+
+from npmctl_cloudflare.client import CloudflareClient
+from npmctl_cloudflare.config import CloudflareConfig
+from npmctl_cloudflare.provider import CloudflareDnsProvider
+
+__all__ = ["CloudflareClient", "CloudflareConfig", "CloudflareDnsProvider"]

npmctl_cloudflare-0.3.6/src/npmctl_cloudflare/client.py

@@ -0,0 +1,121 @@
+"""Small Cloudflare DNS API client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import requests
+
+from npmctl_cloudflare.config import CloudflareConfig
+from npmctl_cloudflare.errors import CloudflareError
+from npmctl_cloudflare.models import CloudflareRecord, CloudflareZone
+
+
+class CloudflareClient:
+    """HTTP client for Cloudflare DNS records."""
+
+    def __init__(self, config: CloudflareConfig, *, timeout_s: float = 15.0) -> None:
+        self.config = config
+        self.timeout_s = timeout_s
+        self.session = requests.Session()
+
+    def zones(self) -> tuple[str, ...]:
+        return tuple(zone.name for zone in self._zones())
+
+    def records(self, zone: str) -> tuple[CloudflareRecord, ...]:
+        zone_id = self._zone_id(zone)
+        return tuple(
+            CloudflareRecord.from_mapping(item)
+            for item in self._request("GET", f"/zones/{zone_id}/dns_records").get("result", [])
+        )
+
+    def create_record(
+        self,
+        zone: str,
+        *,
+        type: str,
+        name: str,
+        value: str,
+        ttl: int | None = None,
+        proxied: bool | None = None,
+    ) -> CloudflareRecord:
+        payload: dict[str, object] = {"type": type.upper(), "name": name, "content": value}
+        if ttl is not None:
+            payload["ttl"] = ttl
+        if proxied is not None:
+            payload["proxied"] = proxied
+        data = self._request("POST", f"/zones/{self._zone_id(zone)}/dns_records", json=payload)
+        return CloudflareRecord.from_mapping(data.get("result", {}))
+
+    def put_record(
+        self,
+        zone: str,
+        record_id: str,
+        *,
+        type: str,
+        name: str,
+        value: str,
+        ttl: int | None = None,
+        proxied: bool | None = None,
+    ) -> CloudflareRecord:
+        payload: dict[str, object] = {"type": type.upper(), "name": name, "content": value}
+        if ttl is not None:
+            payload["ttl"] = ttl
+        if proxied is not None:
+            payload["proxied"] = proxied
+        data = self._request("PUT", f"/zones/{self._zone_id(zone)}/dns_records/{record_id}", json=payload)
+        return CloudflareRecord.from_mapping(data.get("result", {}))
+
+    def patch_record(self, zone: str, record_id: str, **changes: object) -> CloudflareRecord:
+        payload = _cloudflare_payload(changes)
+        data = self._request("PATCH", f"/zones/{self._zone_id(zone)}/dns_records/{record_id}", json=payload)
+        return CloudflareRecord.from_mapping(data.get("result", {}))
+
+    def delete_record(self, zone: str, record_id: str) -> str | None:
+        data = self._request("DELETE", f"/zones/{self._zone_id(zone)}/dns_records/{record_id}")
+        result = data.get("result")
+        if isinstance(result, dict):
+            deleted_id = result.get("id")
+            return None if deleted_id is None else str(deleted_id)
+        return None
+
+    def _zones(self) -> tuple[CloudflareZone, ...]:
+        data = self._request("GET", "/zones")
+        return tuple(CloudflareZone.from_mapping(item) for item in data.get("result", []))
+
+    def _zone_id(self, zone: str) -> str:
+        target = zone.lower().rstrip(".")
+        for item in self._zones():
+            if item.name == target:
+                return item.zone_id
+        raise CloudflareError(f"Cloudflare zone not found: {zone}")
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        response = self.session.request(
+            method,
+            f"{self.config.api_base_url}{path}",
+            headers={"Authorization": f"Bearer {self.config.api_token}"},
+            timeout=self.timeout_s,
+            **kwargs,
+        )
+        if response.status_code < 200 or response.status_code >= 300:
+            raise CloudflareError(f"Cloudflare API failed: HTTP {response.status_code}")
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise CloudflareError("Cloudflare API returned invalid JSON") from exc
+        if data.get("success") is False:
+            messages = [
+                str(item.get("message", "unknown error")) for item in data.get("errors", []) if isinstance(item, dict)
+            ]
+            raise CloudflareError("; ".join(messages) or "Cloudflare API request failed")
+        return data
+
+
+def _cloudflare_payload(changes: dict[str, object]) -> dict[str, object]:
+    payload = dict(changes)
+    if "value" in payload:
+        payload["content"] = payload.pop("value")
+    if "type" in payload and isinstance(payload["type"], str):
+        payload["type"] = payload["type"].upper()
+    return payload

npmctl_cloudflare-0.3.6/src/npmctl_cloudflare/config.py

@@ -0,0 +1,29 @@
+"""Configuration loading for the Cloudflare DNS provider."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Mapping
+
+
+@dataclass(frozen=True, slots=True)
+class CloudflareConfig:
+    """Cloudflare API configuration."""
+
+    api_token: str
+    api_base_url: str = "https://api.cloudflare.com/client/v4"
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> CloudflareConfig:
+        values = os.environ if env is None else env
+        api_token = values.get("CLOUDFLARE_API_TOKEN")
+        if not api_token:
+            raise ValueError("missing Cloudflare config: api_token")
+        return cls(
+            api_token=api_token,
+            api_base_url=values.get("CLOUDFLARE_API_BASE_URL", "https://api.cloudflare.com/client/v4"),
+        )
+
+    def redacted(self) -> dict[str, str | bool]:
+        return {"api_token": bool(self.api_token), "api_base_url": self.api_base_url}

npmctl_cloudflare-0.3.6/src/npmctl_cloudflare/errors.py

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

npmctl_cloudflare-0.3.6/src/npmctl_cloudflare/models.py

@@ -0,0 +1,69 @@
+"""Cloudflare DNS response models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True, slots=True)
+class CloudflareZone:
+    """One Cloudflare zone."""
+
+    zone_id: str
+    name: str
+
+    @classmethod
+    def from_mapping(cls, raw: Mapping[str, Any]) -> CloudflareZone:
+        return cls(zone_id=str(raw.get("id", "")), name=str(raw.get("name", "")).lower().rstrip("."))
+
+
+@dataclass(frozen=True, slots=True)
+class CloudflareRecord:
+    """One Cloudflare DNS record."""
+
+    record_id: str | None
+    name: str
+    type: str
+    value: str
+    ttl: int | None = None
+    proxied: bool | None = None
+
+    @classmethod
+    def from_mapping(cls, raw: Mapping[str, Any]) -> CloudflareRecord:
+        return cls(
+            record_id=_optional_str(raw.get("id")),
+            name=str(raw.get("name", "")).lower().rstrip("."),
+            type=str(raw.get("type", "")).upper(),
+            value=str(raw.get("content", "")),
+            ttl=_optional_int(raw.get("ttl")),
+            proxied=_optional_bool(raw.get("proxied")),
+        )
+
+    def to_dict(self) -> dict[str, str | int | bool | None]:
+        return {
+            "id": self.record_id,
+            "name": self.name,
+            "type": self.type,
+            "value": self.value,
+            "ttl": self.ttl,
+            "proxied": self.proxied,
+        }
+
+
+def _optional_bool(value: Any) -> bool | None:
+    if value is None:
+        return None
+    return bool(value)
+
+
+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_cloudflare-0.3.6/src/npmctl_cloudflare/provider.py

@@ -0,0 +1,27 @@
+"""npmctl DNS provider implementation for Cloudflare."""
+
+from __future__ import annotations
+
+from npmctl_cloudflare.client import CloudflareClient
+from npmctl_cloudflare.config import CloudflareConfig
+
+
+class CloudflareDnsProvider:
+    """DNS provider backed by the Cloudflare DNS Records API."""
+
+    name = "cloudflare"
+
+    def __init__(self, client: CloudflareClient | None = None) -> None:
+        self._client = client
+
+    @property
+    def client(self) -> CloudflareClient:
+        if self._client is None:
+            self._client = CloudflareClient(CloudflareConfig.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_cloudflare-0.3.6/src/npmctl_cloudflare/py.typed

@@ -0,0 +1 @@
+