optout 0.1.0__py3-none-any.whl

optout/__init__.py

@@ -0,0 +1,3 @@
+"""OptOut — self-hosted data broker opt-out tool."""
+
+__version__ = "0.1.0"

optout/brokers/loader.py

@@ -0,0 +1,36 @@
+"""Loads and validates broker YAML files against BrokerDef."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from pydantic import ValidationError
+
+from .schema import BrokerDef
+
+
+def load_broker(path: Path) -> BrokerDef:
+    """Parse and validate a single broker YAML file."""
+    data = yaml.safe_load(path.read_text())
+    try:
+        return BrokerDef.model_validate(data)
+    except ValidationError as exc:
+        raise ValueError(f"Invalid broker definition at {path}:\n{exc}") from exc
+
+
+def load_all_brokers(brokers_dir: Path) -> list[BrokerDef]:
+    """Load every *.yml file in brokers_dir, sorted by slug."""
+    results: list[BrokerDef] = []
+    errors: list[str] = []
+
+    for yml in sorted(brokers_dir.glob("*.yml")):
+        try:
+            results.append(load_broker(yml))
+        except (ValueError, yaml.YAMLError) as exc:
+            errors.append(str(exc))
+
+    if errors:
+        raise ValueError(f"{len(errors)} broker(s) failed validation:\n" + "\n\n".join(errors))
+
+    return results

optout/brokers/registry.py

@@ -0,0 +1,56 @@
+"""In-memory broker catalog, populated from the brokers/ YAML directory."""
+
+from __future__ import annotations
+
+import os
+from importlib.resources import files
+from pathlib import Path
+
+from .loader import load_all_brokers
+from .schema import BrokerDef
+
+_registry: dict[str, BrokerDef] = {}
+_loaded = False
+
+
+def _brokers_dir() -> Path:
+    """Return the directory containing broker YAML files.
+
+    Priority:
+    1. OPTOUT_BROKERS_DIR env var — lets users/tests override with a custom set.
+    2. importlib.resources — finds the YAMLs bundled inside the installed package,
+       works for both editable installs (real filesystem path) and wheel installs.
+    """
+    env = os.environ.get("OPTOUT_BROKERS_DIR")
+    if env:
+        return Path(env)
+    return Path(str(files("optout").joinpath("data/brokers")))
+
+
+def load_registry(brokers_dir: Path | None = None) -> None:
+    global _registry, _loaded
+    directory = brokers_dir or _brokers_dir()
+    if not directory.exists():
+        _registry = {}
+        _loaded = True
+        return
+    _registry = {b.slug: b for b in load_all_brokers(directory)}
+    _loaded = True
+
+
+def _ensure_loaded() -> None:
+    if not _loaded:
+        load_registry()
+
+
+def get_broker(slug: str) -> BrokerDef:
+    _ensure_loaded()
+    try:
+        return _registry[slug]
+    except KeyError:
+        raise KeyError(f"Unknown broker slug: '{slug}'. Run `optout brokers list` to see options.")
+
+
+def all_brokers() -> list[BrokerDef]:
+    _ensure_loaded()
+    return sorted(_registry.values(), key=lambda b: b.name)

optout/brokers/schema.py

@@ -0,0 +1,196 @@
+"""Pydantic models for broker YAML definitions."""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+# ---------------------------------------------------------------------------
+# Resilience primitives
+# ---------------------------------------------------------------------------
+
+
+class RetryConfig(BaseModel):
+    attempts: int = 3
+    backoff_seconds: float = 1.0
+
+
+class StepBase(BaseModel):
+    id: str
+    label: str | None = None
+    retry: RetryConfig | None = None
+    optional: bool = False
+    on_failure: Literal["abort", "skip", "prompt"] = "abort"
+
+
+# ---------------------------------------------------------------------------
+# Step types (discriminated union on `type`)
+# ---------------------------------------------------------------------------
+
+
+class SearchStep(StepBase):
+    type: Literal["search"]
+    search_url_template: str
+    result_selector: str
+    pick_strategy: str = "prompt_user"
+
+
+class NavigateStep(StepBase):
+    type: Literal["navigate"]
+    url: str
+
+
+class FormField(BaseModel):
+    selector: str
+    value: str
+    use_type: bool = False  # type char-by-char; needed for React forms that ignore fill()
+
+
+class FormFillStep(StepBase):
+    type: Literal["form_fill"]
+    fields: dict[str, FormField]
+    frame: str | None = None  # CSS selector for an iframe to fill inside
+
+
+class PromptUserIfPresentStep(StepBase):
+    type: Literal["prompt_user_if_present"]
+    selector: str
+    message: str
+    frame: str | None = None  # CSS selector for an iframe to probe
+
+
+class ClickStep(StepBase):
+    type: Literal["click"]
+    selector: str
+    frame: str | None = None  # CSS selector for an iframe to click inside
+
+
+class SmsVerificationStep(StepBase):
+    type: Literal["sms_verification_prompt"]
+    code_selector: str
+    message: str
+
+
+class CaptureStep(StepBase):
+    type: Literal["capture"]
+    method: str  # "screenshot" is the only current value
+    save_as: str
+
+
+class WaitForStep(StepBase):
+    type: Literal["wait_for"]
+    selector: str | None = None
+    js_condition: str | None = None  # JS predicate: () => bool; polled until truthy
+    timeout_ms: int = 120_000
+    message: str | None = None
+    frame: str | None = None  # CSS selector for an iframe to probe
+
+    @model_validator(mode="after")
+    def _requires_selector_or_condition(self) -> WaitForStep:
+        if not self.selector and not self.js_condition:
+            raise ValueError("wait_for step requires 'selector' or 'js_condition'")
+        return self
+
+
+class OpenInBrowserStep(StepBase):
+    type: Literal["open_in_browser"]
+    url: str
+    instructions: str
+
+
+class CollectInputStep(StepBase):
+    type: Literal["collect_input"]
+    message: str
+    store_as: str  # key written into StepState, e.g. "found_listing_url"
+
+
+class AssertStep(StepBase):
+    type: Literal["assert"]
+    selector: str | None = None
+    text_contains: str | None = None
+    url_matches: str | None = None
+    js_condition: str | None = None
+
+    @model_validator(mode="after")
+    def _requires_at_least_one_condition(self) -> AssertStep:
+        if not any([self.selector, self.text_contains, self.url_matches, self.js_condition]):
+            raise ValueError("assert step requires at least one condition field")
+        return self
+
+
+BrokerStep = Annotated[
+    SearchStep
+    | NavigateStep
+    | FormFillStep
+    | PromptUserIfPresentStep
+    | ClickStep
+    | SmsVerificationStep
+    | CaptureStep
+    | WaitForStep
+    | OpenInBrowserStep
+    | CollectInputStep
+    | AssertStep,
+    Field(discriminator="type"),
+]
+
+
+# ---------------------------------------------------------------------------
+# Scan config (how to check if the user appears on a broker)
+# ---------------------------------------------------------------------------
+
+
+class BrokerScanConfig(BaseModel):
+    search_url_template: str
+    result_selector: str
+    match_fields: list[str] = []
+
+
+# ---------------------------------------------------------------------------
+# Top-level BrokerDef
+# ---------------------------------------------------------------------------
+
+
+class BrokerDef(BaseModel):
+    slug: str
+    name: str
+    domain: str
+    category: str
+    parent_company: str | None = None
+
+    method: Literal["web_form", "email", "postal", "manual"]
+    opt_out_url: str | None = None
+    opt_out_email: str | None = None
+    opt_out_postal_address: str | None = None
+
+    required_fields: list[str] = []
+    optional_fields: list[str] = []
+
+    requires_listing_url: bool = False
+    requires_phone_verification: bool = False
+    requires_email_verification: bool = False
+    requires_id_upload: bool = False
+    requires_notarization: bool = False
+
+    legal_basis: list[str]
+    statutory_response_days: int
+    re_add_window_days: int | None = None
+
+    last_verified_at: date | None = None
+    notes: str | None = None
+
+    scan: BrokerScanConfig | None = None
+    steps: list[BrokerStep] = []
+
+    @model_validator(mode="after")
+    def _method_fields_consistent(self) -> BrokerDef:
+        if self.method == "email" and not self.opt_out_email:
+            raise ValueError(
+                f"Broker '{self.slug}': opt_out_email is required when method is 'email'"
+            )
+        if self.method == "web_form" and not self.opt_out_url:
+            raise ValueError(
+                f"Broker '{self.slug}': opt_out_url is required when method is 'web_form'"
+            )
+        return self