controlid-sdk 0.1.0__py3-none-any.whl

controlid/__init__.py

@@ -0,0 +1,49 @@
+from .client import ControlIDClient
+from .models import (
+    User,
+    Card,
+    QRCard,
+    UserRole,
+    UserGroup,
+    AccessRule,
+    TimeZone,
+    Area,
+    Door,
+    AccessLog,
+    Device,
+    FaceTemplate,
+    CatraInfo,
+    GPIOStatus,
+    CustomField,
+)
+from .exceptions import ControlIDError, AuthenticationError, SessionError, APIError
+from . import constants
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "ControlIDClient",
+    # Models
+    "User",
+    "Card",
+    "QRCard",
+    "UserRole",
+    "UserGroup",
+    "AccessRule",
+    "TimeZone",
+    "Area",
+    "Door",
+    "AccessLog",
+    "Device",
+    "FaceTemplate",
+    "CatraInfo",
+    "GPIOStatus",
+    "CustomField",
+    # Exceptions
+    "ControlIDError",
+    "AuthenticationError",
+    "SessionError",
+    "APIError",
+    # Constants module (handy for card type enums, table names, etc.)
+    "constants",
+]

controlid/client.py

@@ -0,0 +1,514 @@
+import httpx
+import time as _time
+from typing import List, Dict, Any, Optional
+from urllib.parse import quote
+from . import constants as const
+from . import exceptions as ex
+from .models import User, Card, Door, AccessLog, UserRole, QRCard, CustomField
+
+
+class ControlIDClient:
+    """
+    Asynchronous Python client for the ControlID Access Control REST API.
+
+    Usage::
+
+        async with ControlIDClient("https://192.168.1.100", verify=False) as client:
+            users = await client.get_users()
+    """
+
+    def __init__(
+        self,
+        host: str,
+        user: str = "admin",
+        password: str = "admin",
+        timeout: float = 15.0,
+        verify: bool = True,
+    ):
+        self.host = host.rstrip("/")
+        if not self.host.startswith("http"):
+            self.host = f"http://{self.host}"
+
+        self.user = user
+        self.password = password
+        self.session: Optional[str] = None
+        self.timeout = timeout
+        self.verify = verify
+        self._client: Optional[httpx.AsyncClient] = None
+
+    # ─── Context Manager ───────────────────────────────────────────────────────
+
+    async def __aenter__(self) -> "ControlIDClient":
+        self._client = httpx.AsyncClient(timeout=self.timeout, verify=self.verify)
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+    # ─── Internal Helpers ──────────────────────────────────────────────────────
+
+    def _get_url(self, endpoint: str) -> str:
+        """Build a full URL, appending the session token when available."""
+        url = f"{self.host}{endpoint}"
+        if self.session:
+            url += f"?session={quote(self.session, safe='')}"
+        return url
+
+    async def _ensure_client(self):
+        """Create the httpx client if it doesn't exist or was closed."""
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(timeout=self.timeout, verify=self.verify)
+
+    # ─── Authentication ────────────────────────────────────────────────────────
+
+    async def login(self) -> str:
+        """Authenticate with the device and store the session token."""
+        await self._ensure_client()
+        url = f"{self.host}{const.LOGIN}"
+        payload = {"login": self.user, "password": self.password}
+        try:
+            response = await self._client.post(url, json=payload)
+            response.raise_for_status()
+            data = response.json()
+            if "session" in data:
+                self.session = data["session"]
+                return self.session
+            raise ex.AuthenticationError(f"Login failed: {data}")
+        except ex.AuthenticationError:
+            raise
+        except Exception as e:
+            raise ex.AuthenticationError(f"Connection error: {e}")
+
+    async def logout(self):
+        """Invalidate the current session on the device."""
+        if not self.session:
+            return
+        await self._ensure_client()
+        try:
+            await self._client.post(self._get_url(const.LOGOUT))
+        except Exception:
+            pass
+        finally:
+            self.session = None
+
+    async def is_session_valid(self) -> bool:
+        """Returns True if the current session token is still valid."""
+        if not self.session:
+            return False
+        await self._ensure_client()
+        try:
+            response = await self._client.post(self._get_url(const.SESSION_IS_VALID))
+            return response.json().get("session_is_valid", False)
+        except Exception:
+            return False
+
+    # ─── Generic Request Handler ───────────────────────────────────────────────
+
+    async def request(
+        self,
+        endpoint: str,
+        payload: Optional[Dict[str, Any]] = None,
+        method: str = "POST",
+    ) -> Dict[str, Any]:
+        """
+        Send an authenticated request to any API endpoint.
+        Automatically logs in if no session is available, and re-authenticates
+        once on 401 errors (session expired).
+        """
+        await self._ensure_client()
+        if not self.session:
+            await self.login()
+
+        url = self._get_url(endpoint)
+        try:
+            if method.upper() == "POST":
+                response = await self._client.post(url, json=payload or {})
+            else:
+                response = await self._client.get(url)
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 401:
+                # Session expired — re-login and retry once
+                await self.login()
+                url = self._get_url(endpoint)
+                response = await self._client.post(url, json=payload or {})
+                response.raise_for_status()
+                return response.json()
+            raise ex.APIError(
+                f"API Error: {e}",
+                status_code=e.response.status_code,
+                response=e.response.text,
+            )
+        except Exception as e:
+            raise ex.ControlIDError(f"Request failed: {e}")
+
+    # ─── Generic CRUD ──────────────────────────────────────────────────────────
+
+    async def create_objects(self, table: str, values: List[Dict[str, Any]]) -> List[int]:
+        """Insert one or more records into *table*. Returns list of new IDs."""
+        payload = {"object": table, "values": values}
+        data = await self.request(const.CREATE_OBJECTS, payload)
+        return data.get("ids", [])
+
+    async def load_objects(
+        self,
+        table: str,
+        where: Optional[Dict[str, Any]] = None,
+        order: Optional[List[str]] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Query records from *table*.
+
+        ``where`` is a flat dict of field → value conditions, e.g.
+        ``{"id": 5}`` or ``{"name": "Alice"}``.
+        The dict is automatically wrapped in the required ``{"table": {...}}``
+        envelope that the ControlID API expects.
+        """
+        payload: Dict[str, Any] = {"object": table}
+        if where:
+            payload["where"] = {table: where}
+        if order:
+            payload["order"] = order
+        if limit is not None:
+            payload["limit"] = limit
+        if offset is not None:
+            payload["offset"] = offset
+
+        data = await self.request(const.LOAD_OBJECTS, payload)
+        return data.get(table, [])
+
+    async def update_objects(
+        self,
+        table: str,
+        values: Dict[str, Any],
+        where: Optional[Dict[str, Any]] = None,
+    ) -> int:
+        """
+        Update records in *table* that match *where*.
+        Returns the count of affected rows.
+        """
+        payload: Dict[str, Any] = {"object": table, "values": values}
+        if where:
+            payload["where"] = {table: where}
+        data = await self.request(const.UPDATE_OBJECTS, payload)
+        return data.get("count", 0)
+
+    async def destroy_objects(
+        self, table: str, where: Optional[Dict[str, Any]] = None
+    ) -> int:
+        """
+        Delete records from *table* that match *where*.
+        Returns the count of deleted rows.
+        """
+        payload: Dict[str, Any] = {"object": table}
+        if where:
+            payload["where"] = {table: where}
+        data = await self.request(const.DESTROY_OBJECTS, payload)
+        return data.get("count", 0)
+
+    async def upsert_objects(self, table: str, values: List[Dict[str, Any]]) -> List[int]:
+        """
+        Create or update records (create_or_modify_objects.fcgi).
+        Useful for syncing: if a record with the same ID exists, it is updated;
+        otherwise it is created.
+        """
+        payload = {"object": table, "values": values}
+        data = await self.request(const.CREATE_OR_UPDATE_OBJECTS, payload)
+        return data.get("ids", [])
+
+    # ─── Users ────────────────────────────────────────────────────────────────
+
+    async def get_users(self) -> List[User]:
+        """Return all users registered on the device."""
+        return [User(**u) for u in await self.load_objects(const.TABLE_USERS)]
+
+    async def get_user(self, user_id: int) -> Optional[User]:
+        """Return a single user by ID, or None if not found."""
+        rows = await self.load_objects(const.TABLE_USERS, where={"id": user_id})
+        return User(**rows[0]) if rows else None
+
+    async def add_user(self, user: User) -> int:
+        """Create a user and return its new ID."""
+        user_dict = user.model_dump(exclude_none=True)
+        ids = await self.create_objects(const.TABLE_USERS, [user_dict])
+        return ids[0] if ids else None
+
+    async def update_user(self, user_id: int, **fields) -> int:
+        """Patch specific fields on an existing user. Returns affected count."""
+        return await self.update_objects(const.TABLE_USERS, fields, where={"id": user_id})
+
+    async def delete_user(self, user_id: int):
+        """Remove a user from the device."""
+        await self.destroy_objects(const.TABLE_USERS, where={"id": user_id})
+
+    # ─── Cards / Credentials ──────────────────────────────────────────────────
+
+    async def get_cards(self, user_id: Optional[int] = None) -> List[Card]:
+        """Return credentials for all users, or just one user if *user_id* given."""
+        where = {"user_id": user_id} if user_id else None
+        return [Card(**c) for c in await self.load_objects(const.TABLE_CARDS, where=where)]
+
+    async def add_card(self, card: Card) -> int:
+        """Register a credential (RFID, QR, etc.) for a user."""
+        return (await self.create_objects(const.TABLE_CARDS, [card.model_dump(exclude_none=True)]))[0]
+
+    async def delete_card(self, card_id: int):
+        """Remove a credential by ID."""
+        await self.destroy_objects(const.TABLE_CARDS, where={"id": card_id})
+
+    async def add_qr_code(self, user_id: int, qr_value: int) -> int:
+        """
+        Register a QR-code credential for *user_id*.
+        *qr_value* is the integer hash the device expects when the QR is scanned
+        (typically CRC-32 of the string content).
+
+        Note: the `type` field is omitted for compatibility with firmware versions
+        that only accept `value` + `user_id` on the cards table.
+        """
+        return await self.add_card(Card(user_id=user_id, value=qr_value))
+
+    # ─── Groups / Departments ─────────────────────────────────────────────────
+
+    async def get_groups(self) -> List[Dict[str, Any]]:
+        """Return all groups (departments) defined on the device."""
+        return await self.load_objects(const.TABLE_GROUPS)
+
+    async def create_group(self, name: str) -> int:
+        """Create a new group and return its ID."""
+        ids = await self.create_objects(const.TABLE_GROUPS, [{"name": name}])
+        return ids[0] if ids else None
+
+    async def add_user_to_group(self, user_id: int, group_id: int):
+        """Assign a user to a group/department."""
+        await self.create_objects(const.TABLE_USER_GROUPS, [
+            {"user_id": user_id, "group_id": group_id}
+        ])
+
+    async def remove_user_from_group(self, user_id: int, group_id: int):
+        """Remove a user from a group."""
+        await self.destroy_objects(
+            const.TABLE_USER_GROUPS,
+            where={"user_id": user_id, "group_id": group_id},
+        )
+
+    # ─── User Roles / Types ───────────────────────────────────────────────────
+
+    async def get_user_roles(self) -> List[Dict[str, Any]]:
+        """Return all user roles (types) defined on the device."""
+        return await self.load_objects(const.TABLE_USER_ROLES)
+
+    async def create_user_role(self, role: UserRole) -> int:
+        """Create a user role (e.g. Employee, Visitor) and return its ID."""
+        ids = await self.create_objects(
+            const.TABLE_USER_ROLES, [role.model_dump(exclude_none=True)]
+        )
+        return ids[0] if ids else None
+
+    async def assign_user_role(self, user_id: int, role_id: int):
+        """Assign a user to a role type."""
+        await self.upsert_objects(const.TABLE_USER_ROLES, [
+            {"user_id": user_id, "role_id": role_id}
+        ])
+
+    # ─── Access Rules ─────────────────────────────────────────────────────────
+
+    async def get_access_rules(self) -> List[Dict[str, Any]]:
+        """Return all access rules on the device."""
+        return await self.load_objects(const.TABLE_ACCESS_RULES)
+
+    async def create_access_rule(self, name: str, rule_type: int = 1) -> int:
+        """
+        Create an access rule. rule_type 1 = always allowed.
+        Returns the new rule ID.
+        """
+        ids = await self.create_objects(const.TABLE_ACCESS_RULES, [
+            {"name": name, "type": rule_type, "priority": 0}
+        ])
+        return ids[0] if ids else None
+
+    async def assign_group_access_rule(self, group_id: int, rule_id: int):
+        """Grant a group access to doors/areas defined by an access rule."""
+        await self.create_objects(const.TABLE_GROUP_ACCESS_RULES, [
+            {"group_id": group_id, "access_rule_id": rule_id}
+        ])
+
+    # ─── Access Logs ──────────────────────────────────────────────────────────
+
+    async def get_logs(self, limit: int = 20) -> List[AccessLog]:
+        """Return the most recent *limit* access log entries."""
+        rows = await self.load_objects(const.TABLE_ACCESS_LOGS, limit=limit)
+        return [AccessLog(**r) for r in rows]
+
+    # ─── Hardware Actions ─────────────────────────────────────────────────────
+
+    async def execute_actions(self, actions: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """
+        Send one or more hardware action commands.
+        Each action is ``{"action": "<name>", "parameters": "<params>"}``
+        """
+        return await self.request(const.EXECUTE_ACTIONS, {"actions": actions})
+
+    async def open_door(self, door_id: int = 1) -> Dict[str, Any]:
+        """
+        Open a door via internal relay (iDAccess, iDFace Max, etc.).
+        Use ``open_sec_box()`` for devices with an external SecBox module.
+        """
+        return await self.execute_actions([
+            {"action": "door", "parameters": f"door={door_id}"}
+        ])
+
+    async def open_sec_box(self, box_id: int, reason: int = 3) -> Dict[str, Any]:
+        """
+        Open a door via SecBox relay (standard iDFace / iDFlex).
+        *box_id* is the numeric ID of the SecBox as detected by the device.
+        """
+        return await self.execute_actions([
+            {"action": "sec_box", "parameters": f"id={box_id}, reason={reason}"}
+        ])
+
+    # ─── iDFace ───────────────────────────────────────────────────────────────
+
+    async def remote_enroll_face(self, user_id: int, auto: bool = True, countdown: int = 5) -> Dict[str, Any]:
+        """
+        Start a remote face-capture session on the iDFace screen.
+        The user must stand in front of the device while this runs.
+        """
+        payload = {
+            "type": "face",
+            "user_id": user_id,
+            "auto": auto,
+            "save": True,
+            "countdown": countdown
+        }
+        return await self.request(const.REMOTE_ENROLL, payload)
+
+    async def set_user_face_image(self, user_id: int, image_data: bytes) -> Dict[str, Any]:
+        """
+        Upload a JPEG for facial enrollment.
+        Sends raw binary data with the user_id as a query parameter.
+        """
+        await self._ensure_client()
+        if not self.session:
+            await self.login()
+
+        timestamp = int(_time.time())
+        url = self._get_url(const.USER_SET_IMAGE)
+        url += f"&user_id={user_id}&match=1&timestamp={timestamp}"
+
+        try:
+            response = await self._client.post(
+                url,
+                content=image_data,
+                headers={"Content-Type": "application/octet-stream"},
+            )
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            raise ex.ControlIDError(f"Image upload failed: {e}")
+
+    async def get_user_face_image(self, user_id: int) -> bytes:
+        """Download the facial photo stored for a user as raw JPEG bytes."""
+        await self._ensure_client()
+        if not self.session:
+            await self.login()
+
+        url = self._get_url(const.USER_GET_IMAGE)
+        url += f"&user_id={user_id}"
+
+        try:
+            response = await self._client.post(url)
+            response.raise_for_status()
+            return response.content
+        except Exception as e:
+            raise ex.ControlIDError(f"Image download failed: {e}")
+
+    # ─── iDBlock / Turnstile ──────────────────────────────────────────────────
+
+    async def open_turnstile(self, direction: str = "clockwise") -> Dict[str, Any]:
+        """
+        Release the iDBlock turnstile.
+        direction: ``'clockwise'`` | ``'anticlockwise'`` | ``'both'``
+        """
+        return await self.execute_actions([
+            {"action": "catra", "parameters": f"allow={direction}"}
+        ])
+
+    async def open_ballot_box(self) -> Dict[str, Any]:
+        """Release the card-collector slot on an iDBlock."""
+        return await self.execute_actions([
+            {"action": "open_collector", "parameters": ""}
+        ])
+
+    async def get_turnstile_info(self) -> List[Dict[str, Any]]:
+        """Return the turnstile hardware configuration list."""
+        return await self.load_objects(const.TABLE_CATRA_INFOS)
+
+    # ─── GPIO ─────────────────────────────────────────────────────────────────
+
+    async def get_gpio_status(self, gpio_pin: int = 1) -> Dict[str, Any]:
+        """
+        Query the state of a specific GPIO pin.
+        *gpio_pin* — the pin number to query (default 1, e.g. a relay).
+        Returns a dict with the current high/low state.
+        Note: throws 400 Bad Request if the pin is not mapped on your hardware.
+        """
+        return await self.request(const.READ_GPIO_STATUS, payload={"gpio": gpio_pin})
+
+    # ─── Custom Fields (c_users) ──────────────────────────────────────────────
+
+    async def add_custom_field(self, field: CustomField) -> Dict[str, Any]:
+        """
+        Add a new column to the ``c_users`` table.
+
+        Example::
+
+            field = CustomField(column_name="cpf", name="CPF", type="TEXT")
+            await client.add_custom_field(field)
+        """
+        payload = field.model_dump()
+        return await self.request(const.OBJECT_ADD_FIELD, payload)
+
+    async def remove_custom_fields(self, field_ids: List[int]) -> Dict[str, Any]:
+        """Remove custom columns from ``c_users`` by their field IDs."""
+        return await self.request(const.OBJECT_REMOVE_FIELDS, {"ids": field_ids})
+
+    async def get_custom_user_data(self, user_id: int) -> Dict[str, Any]:
+        """Return the custom field values for a specific user."""
+        rows = await self.load_objects(const.TABLE_C_USERS, where={"user_id": user_id})
+        return rows[0] if rows else {}
+
+    async def set_custom_user_data(self, user_id: int, **fields) -> int:
+        """
+        Write arbitrary custom fields for a user.
+
+        Example::
+
+            await client.set_custom_user_data(user_id=5, cpf="123.456.789-00", birthdate="1990-01-01")
+        """
+        existing = await self.load_objects(const.TABLE_C_USERS, where={"user_id": user_id})
+        if existing:
+            return await self.update_objects(
+                const.TABLE_C_USERS, fields, where={"user_id": user_id}
+            )
+        else:
+            await self.create_objects(
+                const.TABLE_C_USERS, [{**fields, "user_id": user_id}]
+            )
+            return 1
+
+    # ─── Device Configuration ─────────────────────────────────────────────────
+
+    async def set_configuration(self, config: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Write device configuration settings.
+
+        Example::
+
+            await client.set_configuration({"face_id": {"qrcode_legacy_mode_enabled": "1"}})
+        """
+        return await self.request(const.SET_CONFIGURATION, config)

controlid/constants.py

@@ -0,0 +1,69 @@
+"""
+Constants for ControlID API.
+"""
+
+# Endpoints
+LOGIN = "/login.fcgi"
+LOGOUT = "/logout.fcgi"
+SESSION_IS_VALID = "/session_is_valid.fcgi"
+
+# Object Management
+CREATE_OBJECTS = "/create_objects.fcgi"
+LOAD_OBJECTS = "/load_objects.fcgi"
+UPDATE_OBJECTS = "/modify_objects.fcgi"
+DESTROY_OBJECTS = "/destroy_objects.fcgi"
+COUNT_OBJECTS = "/count_objects.fcgi"
+CREATE_OR_UPDATE_OBJECTS = "/create_or_modify_objects.fcgi"
+
+# Actions
+REBOOT = "/reboot.fcgi"
+SET_SYSTEM_TIME = "/set_system_time.fcgi"
+GENERATE_DEVICE_ID = "/generate_device_id.fcgi"
+SET_GPIO = "/set_gpio.fcgi"
+GPIO_STATE = "/gpio_state.fcgi"
+REMOTE_ENROLL = "/remote_enroll.fcgi"
+USER_SET_IMAGE = "/user_set_image.fcgi"
+USER_GET_IMAGE = "/user_get_image.fcgi"
+EXECUTE_ACTIONS = "/execute_actions.fcgi"
+READ_GPIO_STATUS = "/gpio_state.fcgi"
+SET_CONFIGURATION = "/set_configuration.fcgi"
+
+# Custom Fields (c_users)
+OBJECT_ADD_FIELD = "/object_add_field.fcgi"
+OBJECT_REMOVE_FIELDS = "/object_remove_fields.fcgi"
+OBJECT_METADATA = "/object_metadata.fcgi"
+
+# Export
+EXPORT_OBJECTS = "/export_objects.fcgi"
+
+# Common Table/Object Names
+TABLE_USERS = "users"
+TABLE_CARDS = "cards"
+TABLE_FINGERPRINTS = "fingerprints"
+TABLE_FACE_TEMPLATES = "face_templates"
+TABLE_ACCESS_RULES = "access_rules"
+TABLE_GROUPS = "groups"
+TABLE_TIME_ZONES = "time_zones"
+TABLE_AREAS = "areas"
+TABLE_PORTALS = "portals"
+TABLE_DOORS = "doors"
+TABLE_DEVICES = "devices"
+TABLE_ACCESS_LOGS = "access_logs"
+TABLE_USER_GROUPS = "user_groups"
+TABLE_GROUP_ACCESS_RULES = "group_access_rules"
+TABLE_AREA_ACCESS_RULES = "area_access_rules"
+TABLE_CATRA_INFOS = "catra_infos"
+TABLE_USER_ROLES = "user_roles"   # User types / roles
+TABLE_C_USERS = "c_users"         # Custom user fields table
+
+# Card Types / Identifier types
+CARD_TYPE_CARD = 0          # Standard RFID card
+CARD_TYPE_QR = 1            # QR Code
+CARD_TYPE_BIOMETRIC = 2     # Fingerprint
+CARD_TYPE_PASSWORD = 3      # Password
+CARD_TYPE_FACE = 4          # Face recognition
+
+# User Types (user role IDs as used in user_roles table)
+USER_EMPLOYEE = 1
+USER_VISITOR = 2
+USER_MANAGER = 4

controlid/exceptions.py

@@ -0,0 +1,22 @@
+class ControlIDError(Exception):
+    """Base exception for ControlID SDK."""
+    pass
+
+class AuthenticationError(ControlIDError):
+    """Raised when authentication fails."""
+    pass
+
+class SessionError(ControlIDError):
+    """Raised when there is an issue with the session."""
+    pass
+
+class APIError(ControlIDError):
+    """Raised when the API returns an error response."""
+    def __init__(self, message, status_code=None, response=None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+        
+class ObjectError(ControlIDError):
+    """Raised when an object operation fails."""
+    pass

controlid/models.py

@@ -0,0 +1,132 @@
+from pydantic import BaseModel, Field
+from typing import Optional, List, Dict, Any
+
+
+# ─── Core Models ───────────────────────────────────────────────────────────────
+
+class User(BaseModel):
+    id: Optional[int] = None
+    name: str
+    registration: str = ""
+    password: Optional[str] = ""
+    salt: Optional[str] = ""
+
+
+class Card(BaseModel):
+    id: Optional[int] = None
+    value: int
+    user_id: int
+    # NOTE: the 'type' field is NOT supported by all device firmware versions.
+    # Only include it if your device accepts it (check load_objects on 'cards').
+    type: Optional[int] = None     # 0=RFID, 1=QR — exclude_none keeps it off by default
+
+
+class UserGroup(BaseModel):
+    id: Optional[int] = None
+    name: str
+
+
+class AccessRule(BaseModel):
+    id: Optional[int] = None
+    name: str
+    type: int = 1          # 1: Always allowed
+    priority: int = 0
+
+
+class TimeZone(BaseModel):
+    id: Optional[int] = None
+    name: str
+    # week schedule bits are stored inside the device, not here
+
+
+class Area(BaseModel):
+    id: Optional[int] = None
+    name: str
+
+
+class Door(BaseModel):
+    id: Optional[int] = None
+    name: str
+    hostname: Optional[str] = None
+
+
+class AccessLog(BaseModel):
+    id: int
+    time: int
+    event: int
+    device_id: int
+    identifier_id: int
+    user_id: int
+    portal_id: int
+
+
+class Device(BaseModel):
+    id: Optional[int] = None
+    name: str
+    ip: str
+    public_key: Optional[str] = None
+
+
+# ─── Biometrics ────────────────────────────────────────────────────────────────
+
+class FaceTemplate(BaseModel):
+    id: Optional[int] = None
+    user_id: int
+    template: str          # Base64 encoded
+
+
+# ─── iDBlock / Hardware ────────────────────────────────────────────────────────
+
+class CatraInfo(BaseModel):
+    id: Optional[int] = None
+    name: str
+    mode: int = 0          # 0: Standard, 1: Pro, 2: Enterprise
+
+
+class GPIOStatus(BaseModel):
+    inputs: Dict[str, int]
+    outputs: Dict[str, int]
+
+
+# ─── User Roles / Types ────────────────────────────────────────────────────────
+
+class UserRole(BaseModel):
+    """
+    Defines a type/role for users (e.g. Employee, Visitor, Manager).
+    Stored in the 'user_roles' table on the device.
+    """
+    id: Optional[int] = None
+    name: str
+    expire_on: Optional[int] = None     # Unix timestamp; None = never expires
+    begin_time: Optional[int] = None    # Seconds from midnight
+    end_time: Optional[int] = None      # Seconds from midnight
+    max_uses: Optional[int] = None      # -1 = unlimited
+
+
+# ─── QR Code / Visitor Cards ──────────────────────────────────────────────────
+
+class QRCard(BaseModel):
+    """
+    A QR-code credential. The 'value' field stores the card hash;
+    'type' is always 1 (QR Code) on the device.
+    """
+    id: Optional[int] = None
+    value: int
+    user_id: int
+    type: int = 1          # 1 = QR Code
+
+
+# ─── Custom Fields ─────────────────────────────────────────────────────────────
+
+class CustomField(BaseModel):
+    """
+    Defines a schema for a new column in the c_users table.
+    Use ControlIDClient.add_custom_field() to persist this on the device.
+    """
+    object: str = "c_users"
+    column_name: str        # e.g. "cpf", "birthdate"
+    name: str               # Human-readable label
+    type: str = "TEXT"      # TEXT | INTEGER | REAL | BLOB
+    constraint: str = "NONE"
+    default_value: str = ""
+    unique: bool = False

controlid_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: controlid-sdk
+Version: 0.1.0
+Summary: A Python SDK for ControlID access control devices.
+Author-email: Tulio Amancio <root@tsuriu.com.br>
+Project-URL: Homepage, https://github.com/tulioamancio/controlid-python-sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+
+# ControlID Python SDK (Async)
+
+A production-ready, high-performance asynchronous Python SDK for ControlID access control devices (iDAccess, iDFace, iDFlex, iDBlock, etc.). 
+
+Built on top of `httpx` and `pydantic` v2, this SDK provides robust abstractions over the ControlID API, gracefully handling undocumented firmware quirks, session management, and complex data schemas.
+
+## Features
+
+- ⚡️ **Fully Asynchronous**: Built exclusively on `async/await` and `httpx` for high-concurrency non-blocking I/O.
+- 🔑 **Automatic Session Management**: Handles logins and injects secure, URL-encoded tokens into requests.
+- 🛡️ **Pydantic Validation**: Robust, type-hinted data models (`User`, `Card`, `AccessRule`, etc.).
+- 🛠️ **Quirk Resolution**: Automatically manages device-specific API quirks (e.g., nested `where` clauses, strict `modify_objects` routing, implicit schema limitations).
+- 📸 **Facial Recognition**: Push direct binary payload image uploads for iDFace enrollment.
+- 📱 **QR Code Support**: Generate and register CRC-32 QR Code credentials safely.
+- 🚪 **Advanced Hardware Control**: Interact with relays, GPIO pins, SecBoxes, turnstiles (catras), and ballot boxes.
+- 📋 **Dynamic Schemas**: Native support for creating and interacting with custom device fields (`c_users` table).
+
+## Installation
+
+```bash
+pip install .
+```
+
+## Quick Start
+
+```python
+import asyncio
+from controlid import ControlIDClient, User
+
+async def main():
+    # Use as an async context manager for automatic session cleanup.
+    # We use verify=False typically because devices use self-signed SSL certificates.
+    async with ControlIDClient(
+        host="https://192.168.0.100", 
+        user="admin", 
+        password="password", 
+        verify=False
+    ) as client:
+        
+        # 1. Fetch Users
+        users = await client.get_users()
+        print(f"Found {len(users)} users on device.")
+
+        # 2. Add a new user
+        user_id = await client.add_user(User(name="Jane Doe", registration="EMP-001"))
+        print(f"Created user with ID: {user_id}")
+
+        # 3. Open a Door (using internal relay)
+        await client.open_door(door_id=1)
+        
+        # Or using an external SecBox (standard on iDFace/iDFlex installations)
+        # await client.open_sec_box(box_id=65793)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Supported Workflows
+
+This SDK provides extensive high-level wrappers. Below are just a few examples. 
+
+*(For complete runnable scripts, check the `examples/` directory).*
+
+### 📸 Facial Recognition & Photo Upload
+Unlike standard JSON requests, facial photo enrollment requires raw binary streaming. 
+The iDFace firmware is famously strict: if you upload a high-resolution, dense portrait (like a 2MB iPhone photo) or images where the face isn't perfectly centered, the device will silently reject the neural-network validation with a `400 Bad Request`.
+
+Our SDK examples handle this elegantly by using `Pillow` to instantly downscale huge images to `< 40KB` and `< 600x600px` before uploading:
+
+```python
+from examples import helper
+
+# Automatically loops through photos, shrinks them flawlessly, and registers the face!
+await helper.enhance_user(client, user_id=10, user_ref="EMP")
+```
+
+Alternatively, you can skip local uploads entirely and trigger the device's physical screen so the person can enroll themselves live at the gate!
+
+```python
+# The iDFace terminal will open its camera, display a 5-second countdown,
+# analyze liveness, and automatically save the biometric hash!
+await client.remote_enroll_face(user_id=10, auto=True, countdown=5)
+```
+
+### 📱 QR Code Credentials
+The device expects CRC-32 integers when scanning standard QR codes. The SDK can help you register them correctly.
+
+```python
+import binascii
+
+def qr_hash(text: str) -> int:
+    return binascii.crc32(text.encode()) & 0xFFFFFFFF
+
+# Give a user a QR code credential that matches the text "VISITOR-99"
+await client.add_qr_code(user_id=10, qr_value=qr_hash("VISITOR-99"))
+```
+*Note: Our `examples/helper.py` will automatically generate and save physical `.png` files of the QR Codes so you can test them instantly on your screen or phone.*
+
+### 🏢 Departments, Groups, and Access Rules
+Organize your users logically and restrict their access using Rules and Groups.
+
+```python
+# 1. Create a Department 
+group_id = await client.create_group("Engineering")
+
+# 2. Create an Access Rule (e.g., 1 = Always Allowed, Priority = 0)
+rule_id = await client.create_access_rule("24/7 Access", rule_type=1)
+
+# 3. Link the Group to the Rule
+await client.assign_group_access_rule(group_id, rule_id)
+
+# 4. Add the user to the Group
+await client.add_user_to_group(user_id=10, group_id=group_id)
+```
+
+### 🧩 Custom Fields (`c_users`)
+Extend the device's native database schema dynamically to store your own business logic (e.g., CPF, Department Code).
+
+```python
+from controlid import CustomField
+
+# 1. Create the schema column (run once per device)
+await client.add_custom_field(CustomField(
+    column_name="cpf",
+    name="CPF Number",
+    type="TEXT"
+))
+
+# 2. Write data for a specific user
+await client.set_custom_user_data(user_id=10, cpf="123.456.789-00")
+
+# 3. Read it back
+custom_data = await client.get_custom_user_data(user_id=10)
+print(custom_data) # {'cpf': '123.456.789-00', 'user_id': 10}
+```
+
+### ⚙️ Generic Object API
+For device tables that lack specialized wrappers, you can always bypass the abstractions and use the highly resilient Generic Database API:
+
+```python
+# Fetch from any device table seamlessly
+roles = await client.load_objects("user_roles")
+
+# Safely update using Python dicts. 
+# The SDK automatically handles the internal 'where' namespace quirks.
+await client.modify_objects(
+    "users", 
+    values={"name": "New Name"}, 
+    where={"id": 10}
+)
+```
+
+## Directory Structure
+- `src/controlid/client.py`: Core asynchronous logic and endpoints.
+- `src/controlid/models.py`: Pydantic V2 definitions.
+- `src/controlid/constants.py`: Enums and endpoint tables.
+- `examples/*.py`: Fully self-contained scripts demonstrating every major use-case. Including a comprehensive `run_tests.py` that validates the entire API sequentially against live hardware.
+
+## License
+MIT

controlid_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+controlid/__init__.py,sha256=D4xaa7Gq_Zmx68QOkkyAiyin3H70xpJNX3krrgmMp7E,869
+controlid/client.py,sha256=7VGuzNai7iyC1dPX7wqZJqkH2TfKk0q_ahfU_pqV3WE,22075
+controlid/constants.py,sha256=l4Nmx-jIXN4zE79Y4UqJvD5ZPgsyIcYOaRKBwuUM_lw,2068
+controlid/exceptions.py,sha256=LXCsDIphLkPwgiFqqcdNnvPr1ZrSSG03oc8vnWrDKUo,651
+controlid/models.py,sha256=fuQxZHTZt59ng-ZfMPKNS7TnINGQmY2aQQx3qfCI3_U,4135
+controlid_sdk-0.1.0.dist-info/METADATA,sha256=nO4eR7io7smW-WF2n_mI0PwU3aMsZ8JItRqEp4uNE6g,6750
+controlid_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+controlid_sdk-0.1.0.dist-info/top_level.txt,sha256=kSKmrNmAEx26i0W8Rs_Fn-pg7EB9uT0ILrG6PUp1TZY,10
+controlid_sdk-0.1.0.dist-info/RECORD,,

controlid_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

controlid_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+controlid