Directory People Helper

from typing import Any, Dict, List, Optional

class DirectoryClient:
    def __init__(self, connection: Any, base_dn: str):
        """
        Create a directory client bound to a base DN using an existing connection.
        The client should rely on the high-level abstraction layer for schema-aware access.
        """

    def bootstrap_people_schema(self) -> None:
        """
        Define and cache the object/attribute model for person entries.
        Maps raw directory attributes to friendly keys: dn, name, email, department,
        manager (resolved to common name), and created_at (ISO string).
        Applies default department when missing and validates that email values contain '@'.
        """

    def find_people(self, query: str, include_operational: bool = False,
                    page_size: Optional[int] = None) -> List[Dict[str, Any]]:
        """
        Search under the base DN using simplified query syntax (e.g., 'name: Alice* & department: Engineering').
        Returns dictionaries ordered by name with keys dn, name, email, department, manager, created_at.
        If include_operational is True, include operational timestamp data; omit when False.
        When page_size is provided, iterate through all result pages automatically and merge them.
        """

    def update_department(self, entry_dn: str, department: str) -> bool:
        """
        Update the department for the entry identified by entry_dn using the abstraction layer's write support.
        Commits the change immediately and clears any pending operations.
        Returns True when the server acknowledges the update.
        """

    def rename_person(self, entry_dn: str, new_rdn: str) -> bool:
        """
        Rename the entry's relative distinguished name and refresh its data.
        Returns True when the rename succeeds and follow-up reads surface the new DN.
        """