Document canonical plugin architecture

examples/plugin_template/client.py

@@ -0,0 +1,56 @@
+"""Private native client for the example dns-sync plugin."""
+
+from dataclasses import dataclass
+
+from dns_sync.adapters import Endpoint
+
+
+@dataclass(frozen=True)
+class ExampleRecord:
+    """Endpoint-native record used only by this plugin."""
+
+    local_key: str
+    hostname: str
+    ip: str
+    record_type: str = "A"
+
+
+class ExampleClient:
+    """Client for one explicit example endpoint."""
+
+    def __init__(self, endpoint: Endpoint):
+        if endpoint.plugin != "example":
+            raise RuntimeError(
+                "ExampleClient requires an example endpoint"
+            )
+
+        self.endpoint = endpoint
+
+    def connect(self) -> None:
+        """Authenticate or initialize the native connection."""
+        raise NotImplementedError
+
+    def list_records(self) -> list[ExampleRecord]:
+        """Return endpoint-native records."""
+        raise NotImplementedError
+
+    def add_record(
+        self,
+        record: ExampleRecord,
+    ) -> str | None:
+        """Create one native record."""
+        raise NotImplementedError
+
+    def update_record(
+        self,
+        record: ExampleRecord,
+    ) -> str | None:
+        """Update one native record."""
+        raise NotImplementedError
+
+    def verify_record(
+        self,
+        record: ExampleRecord,
+    ) -> bool:
+        """Verify endpoint-native state."""
+        raise NotImplementedError