suprema-biostar-mcp 1.0.1__py3-none-any.whl

biostar_x_mcp_server/handlers/card_handler.py

@@ -0,0 +1,746 @@
+# handlers/card_handler.py
+import logging
+import re
+from typing import Sequence, Dict, Any, Optional, List
+
+import httpx
+
+from .base_handler import BaseHandler
+
+logger = logging.getLogger(__name__)
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Fixed mapping by BioStar 2 spec (card_type.id)
+# ─────────────────────────────────────────────────────────────────────────────
+CARD_KIND_TO_ID = {
+    "CSN": 0,
+    "WIEGAND": 1,
+    "SECURE_CREDENTIAL": 2,
+    "ACCESS_ON_CARD": 3,
+    "MOBILE_CSN": 4,
+    "WIEGAND_MOBILE": 5,
+    "QR_BARCODE": 6,
+    "BIOSTAR2_QR": 7,
+}
+
+# card_type.type fallback when GET /api/cards/types is missing or incomplete
+TYPE_FALLBACK: Dict[int, int] = {
+    0: 1,   # CSN
+    1: 10,  # WIEGAND -> CSN_WIEGAND
+    2: 2,   # SECURE CREDENTIAL
+    3: 3,   # ACCESS ON CARD
+    4: 4,   # MOBILE CSN
+    5: 5,   # WIEGAND MOBILE
+    6: 6,   # QR/BARCODE
+    7: 7,   # BIOSTAR2 QR
+}
+
+# Common Wiegand format aliases
+WIEGAND_FORMAT_ALIAS: Dict[str, int] = {
+    "26bit": 0, "26-bit": 0, "h10301": 0, "sia26": 0,
+    "hid37": 1, "h10302": 1, "37bit": 1, "37-bit": 1,
+}
+
+# Hard constraints (fail if violated)
+WIEGAND_CONSTRAINTS: Dict[int, Dict[str, Any]] = {
+    # 26bit SIA Standard (H10301)
+    0: {
+        "name": "26bit SIA Standard (H10301)",
+        "facility_min": 0, "facility_max": 255,
+        "card_min": 0,     "card_max": 65535,
+        "example_display": "12-3456",
+    },
+    # HID 37bit (H10302)
+    1: {
+        "name": "HID 37bit (H10302)",
+        "facility_min": 0, "facility_max": 65535,
+        "card_min": 0,     "card_max": 524287,
+        "example_display": "100-12345",
+    },
+}
+
+# Presets for UX (includes constraints)
+WIEGAND_PRESETS: List[Dict[str, Any]] = [
+    {
+        "id": 0,
+        "name": WIEGAND_CONSTRAINTS[0]["name"],
+        "aliases": ["26bit", "h10301", "sia26"],
+        "hint": f"display_card_id like '{WIEGAND_CONSTRAINTS[0]['example_display']}'",
+        "constraints": {
+            "facility_code": [WIEGAND_CONSTRAINTS[0]["facility_min"], WIEGAND_CONSTRAINTS[0]["facility_max"]],
+            "card_number":   [WIEGAND_CONSTRAINTS[0]["card_min"],     WIEGAND_CONSTRAINTS[0]["card_max"]],
+        },
+    },
+    {
+        "id": 1,
+        "name": WIEGAND_CONSTRAINTS[1]["name"],
+        "aliases": ["hid37", "h10302", "37bit"],
+        "hint": f"display_card_id like '{WIEGAND_CONSTRAINTS[1]['example_display']}'",
+        "constraints": {
+            "facility_code": [WIEGAND_CONSTRAINTS[1]["facility_min"], WIEGAND_CONSTRAINTS[1]["facility_max"]],
+            "card_number":   [WIEGAND_CONSTRAINTS[1]["card_min"],     WIEGAND_CONSTRAINTS[1]["card_max"]],
+        },
+    },
+]
+
+# CSN validation rules
+CSN_RULES = {
+    "min_len": 1,
+    "max_len": 32,
+    "no_leading_zero": True,
+    # strictly '0-9' (no Unicode digits)
+    "ascii_digits_only": True,
+}
+
+def _ascii_digits(s: str) -> bool:
+    """Return True if string contains ASCII digits only (0-9)."""
+    return bool(re.fullmatch(r"[0-9]+", s))
+
+
+class CardsHandler(BaseHandler):
+    """
+    Handle card-related operations:
+      - per-type create
+      - card types lookup
+      - availability check
+      - optional assignment to user (PUT preferred, POST legacy fallback)
+    """
+
+    # ──────────────────────────── helpers ────────────────────────────
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "bs-session-id": self.get_session_id(),
+            "Content-Type": "application/json",
+        }
+
+    async def _get_card_types_map(self) -> Dict[int, List[int]]:
+        """
+        GET /api/cards/types -> { card_type_id(int): [allowed type ints] }
+        Adjust parsing if your server responds differently.
+        """
+        self.check_auth()
+        url = f"{self.session.config.biostar_url}/api/cards/types"
+        async with httpx.AsyncClient(verify=False) as client:
+            resp = await client.get(url, headers=self._headers())
+        if resp.status_code != 200:
+            raise RuntimeError(f"Failed to get card types: {resp.status_code} - {resp.text}")
+
+        data = resp.json()
+        rows = (
+            data.get("CardTypes", {}).get("rows")
+            or data.get("rows")
+            or data.get("data")
+            or []
+        )
+
+        types_map: Dict[int, List[int]] = {}
+        for row in rows:
+            try:
+                cid = int(row.get("id"))
+                if "types" in row and isinstance(row["types"], list):
+                    types_map[cid] = [int(x) for x in row["types"]]
+                elif "type" in row:
+                    types_map[cid] = [int(row["type"])]
+            except Exception:
+                continue
+        return types_map
+
+    async def _resolve_type(self, card_type_id: int, explicit: Optional[int]) -> int:
+        """Return explicit type if given; otherwise resolve from /api/cards/types with fallback."""
+        if explicit is not None:
+            return int(explicit)
+        try:
+            types_map = await self._get_card_types_map()
+            cand = types_map.get(int(card_type_id))
+            if cand and len(cand) > 0:
+                return int(cand[0])
+        except Exception as e:
+            logger.warning(f"_resolve_type: failed to fetch types, using fallback. reason={e}")
+
+        if int(card_type_id) in TYPE_FALLBACK:
+            return TYPE_FALLBACK[int(card_type_id)]
+        raise RuntimeError(f"No available 'type' for card_type.id={card_type_id}")
+
+    async def _check_availability(self, card_id: str) -> bool:
+        """
+        Check via GET /api/v2/cards/registered/?card_id=...
+        If response contains "Card", it's already registered -> not available.
+        If only "Response":{"code":"0"} without "Card", it's available.
+        If endpoint not present (non-200), optimistically return True (server will enforce duplicates).
+        """
+        self.check_auth()
+        url = f"{self.session.config.biostar_url}/api/v2/cards/registered/"
+        params = {"card_id": card_id}
+        async with httpx.AsyncClient(verify=False) as client:
+            resp = await client.get(url, headers=self._headers(), params=params)
+
+        if resp.status_code != 200:
+            logger.info(f"_check_availability: endpoint unavailable or error {resp.status_code}, optimistic True")
+            return True
+
+        try:
+            data = resp.json()
+        except Exception:
+            return True
+
+        not_registered = "Card" not in data
+        return not_registered
+
+    # ── CSN validation ───────────────────────────────────────────────────────
+    def _validate_csn(self, card_id: str) -> Optional[str]:
+        """
+        CSN must follow:
+        - ASCII digits only (0-9)
+        - cannot start with '0' (configurable)
+        - length 1..32
+        """
+        s = (card_id or "").strip()
+        if not (CSN_RULES["min_len"] <= len(s) <= CSN_RULES["max_len"]):
+            return (
+                f"Invalid CSN card_id length. It must be {CSN_RULES['min_len']}–{CSN_RULES['max_len']} "
+                f"ASCII digits."
+            )
+        if CSN_RULES["ascii_digits_only"] and not _ascii_digits(s):
+            return "CSN card_id must contain ASCII digits only (0-9)."
+        if CSN_RULES["no_leading_zero"] and s.startswith("0"):
+            return "CSN card_id must not start with '0'."
+        return None
+
+    # ── Wiegand-specific validation ──────────────────────────────────────────
+    def _get_wiegand_constraints(self, wf_id: int) -> Optional[Dict[str, Any]]:
+        return WIEGAND_CONSTRAINTS.get(int(wf_id))
+
+    def _validate_display_card_id(self, display_card_id: str) -> Optional[str]:
+        """
+        Must be strictly numeric "FC-ID", e.g., "12-3456".
+        """
+        if not isinstance(display_card_id, str):
+            return "display_card_id must be a string like '12-3456'."
+        if not re.fullmatch(r"\d+-\d+", display_card_id):
+            return "display_card_id must be numeric 'FC-ID' (e.g., '12-3456')."
+        return None
+
+    def _validate_wiegand_values(
+        self,
+        *,
+        wf_id: int,
+        facility_code: Any,
+        card_number: Any,
+        display_card_id: Optional[str],
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Return None if valid; otherwise return an error dict suitable for error_response details.
+        """
+        c = self._get_wiegand_constraints(wf_id)
+        if not c:
+            return {
+                "reason": "Unsupported Wiegand format id",
+                "wiegand_format_id": wf_id,
+                "supported_format_ids": list(WIEGAND_CONSTRAINTS.keys()),
+            }
+
+        # numeric checks
+        try:
+            fc = int(facility_code)
+            cn = int(card_number)
+        except Exception:
+            return {
+                "reason": "facility_code and card_number must be integers",
+                "got": {"facility_code": facility_code, "card_number": card_number},
+            }
+
+        # range checks
+        fc_min, fc_max = c["facility_min"], c["facility_max"]
+        cn_min, cn_max = c["card_min"], c["card_max"]
+        fc_ok = (fc_min <= fc <= fc_max)
+        cn_ok = (cn_min <= cn <= cn_max)
+        if not fc_ok or not cn_ok:
+            return {
+                "reason": "Wiegand value out of range",
+                "format": c["name"],
+                "expected_ranges": {
+                    "facility_code": [fc_min, fc_max],
+                    "card_number": [cn_min, cn_max],
+                },
+                "got": {"facility_code": facility_code, "card_number": card_number},
+                "hint": f"Try display_card_id like '{c['example_display']}'",
+            }
+
+        # display_card_id pattern + consistency with fc/cn
+        if display_card_id is not None:
+            msg = self._validate_display_card_id(display_card_id)
+            if msg:
+                return {
+                    "reason": msg,
+                    "example": c["example_display"],
+                }
+            # match to fc-cn
+            m = display_card_id.split("-")
+            dfc, dcn = int(m[0]), int(m[1])
+            if dfc != fc or dcn != cn:
+                return {
+                    "reason": "display_card_id must match facility_code and card_number",
+                    "expected": f"{fc}-{cn}",
+                    "got": display_card_id,
+                }
+
+        # all good
+        return None
+
+    def _rows_payload(
+        self,
+        card_id: str,
+        card_type_id: int,
+        card_type_type: int,
+        *,
+        wiegand_format_id: Optional[int] = None,
+        mobile_opts: Optional[Dict[str, Any]] = None,
+        display_card_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Build POST /api/cards payload
+        """
+        row: Dict[str, Any] = {
+            "card_id": str(card_id),
+            "card_type": {"id": str(int(card_type_id)), "type": str(int(card_type_type))},
+        }
+
+        if wiegand_format_id is not None:
+            row["wiegand_format_id"] = {"id": str(int(wiegand_format_id))}
+
+        if display_card_id:
+            row["display_card_id"] = str(display_card_id)
+
+        if mobile_opts:
+            for k in ("isUserPhoto", "isDepartment", "isTitle", "start_datetime", "expiry_datetime"):
+                if k in mobile_opts and mobile_opts[k] is not None:
+                    row[k] = mobile_opts[k]
+            if "display_card_id" in mobile_opts and mobile_opts["display_card_id"]:
+                row["display_card_id"] = mobile_opts["display_card_id"]
+
+        return {"CardCollection": {"rows": [row]}}
+
+    async def _post_create(self, payload: Dict[str, Any]) -> httpx.Response:
+        self.check_auth()
+        url = f"{self.session.config.biostar_url}/api/cards"
+        async with httpx.AsyncClient(verify=False) as client:
+            resp = await client.post(url, headers=self._headers(), json=payload)
+        return resp
+
+    # ── Assignment helpers ─────────────────────────────────────────────────
+    async def _assign_to_user_put(
+        self,
+        user_id: str,
+        create_json: Dict[str, Any],
+        *,
+        card_id: str,
+        card_type_id: int,
+        card_type_type: int,
+    ) -> Dict[str, Any]:
+        """
+        Preferred: PUT /api/users/{user_id} with {"User":{"cards":[{...}]}}
+        """
+        created_rows = (create_json.get("CardCollection") or {}).get("rows") or []
+        created_row = created_rows[0] if created_rows else {}
+
+        card_payload = {
+            **({"id": str(created_row.get("id"))} if created_row.get("id") is not None else {}),
+            "card_id": str(card_id),
+            "display_card_id": str(created_row.get("display_card_id") or card_id),
+            "status": "1",
+            "is_blocked": "false",
+            "is_assigned": "true",
+            "card_type": {
+                "id": str(card_type_id),
+                "type": str(card_type_type),
+            },
+            "mobile_card": "false",
+            "issue_count": "1",
+            "card_slot": "1",
+            "card_mask": "0",
+            "wiegand_format_id": {"id": str((created_row.get("wiegand_format_id") or {}).get("id") or 0)},
+            "start_datetime": created_row.get("start_datetime") or "2001-01-01T00:00:00.00Z",
+            "expiry_datetime": created_row.get("expiry_datetime") or "2030-12-31T23:59:00.00Z",
+        }
+
+        payload = {"User": {"cards": [card_payload]}}
+        url = f"{self.session.config.biostar_url}/api/users/{user_id}"
+        async with httpx.AsyncClient(verify=False) as client:
+            resp = await client.put(url, headers=self._headers(), json=payload)
+
+        if resp.status_code != 200:
+            return {
+                "assigned": False,
+                "method": "PUT",
+                "status": resp.status_code,
+                "error": resp.text,
+                "request_body": payload,
+            }
+        return {
+            "assigned": True,
+            "method": "PUT",
+            "response": resp.json(),
+            "request_body": payload,
+        }
+
+    async def _assign_to_user_post_legacy(
+        self,
+        user_id: str,
+        *,
+        card_id: str,
+        card_type_id: int,
+        card_type_type: int,
+    ) -> Dict[str, Any]:
+        """
+        Legacy fallback: POST /api/users/{user_id}/cards with {"Card":{...}}
+        """
+        payload = {
+            "Card": {
+                "card_id": str(card_id),
+                "card_type": {"id": str(card_type_id), "type": str(card_type_type)},
+            }
+        }
+        url = f"{self.session.config.biostar_url}/api/users/{user_id}/cards"
+        async with httpx.AsyncClient(verify=False) as client:
+            resp = await client.post(url, headers=self._headers(), json=payload)
+
+        if resp.status_code != 200:
+            return {
+                "assigned": False,
+                "method": "POST",  # fixed typo from earlier
+                "status": resp.status_code,
+                "error": resp.text,
+                "request_body": payload,
+            }
+        return {
+            "assigned": True,
+            "method": "POST",
+            "response": resp.json(),
+            "request_body": payload,
+        }
+
+    async def _assign_to_user(
+        self,
+        user_id: str,
+        create_json: Dict[str, Any],
+        *,
+        card_id: str,
+        card_type_id: int,
+        card_type_type: int,
+    ) -> Dict[str, Any]:
+        """
+        Try PUT first; if it fails, fallback to POST legacy endpoint.
+        """
+        put_res = await self._assign_to_user_put(
+            user_id,
+            create_json,
+            card_id=card_id,
+            card_type_id=card_type_id,
+            card_type_type=card_type_type,
+        )
+        if put_res.get("assigned"):
+            return put_res
+        post_res = await self._assign_to_user_post_legacy(
+            user_id,
+            card_id=card_id,
+            card_type_id=card_type_id,
+            card_type_type=card_type_type,
+        )
+        return {"put": put_res, "post": post_res, "assigned": bool(post_res.get("assigned"))}
+
+    # ── Creation flow ────────────────────────────────────────────────────────
+    async def _create_card_flow(
+        self,
+        *,
+        card_id_raw: Any,
+        card_type_id: int,
+        card_type_type_raw: Optional[Any],
+        assign_to_user_id: Optional[Any],
+        skip_availability_check: bool,
+        dry_run: bool,
+        validate_csn: bool = False,
+        extra_payload: Optional[Dict[str, Any]] = None,
+    ) -> Sequence[Dict[str, Any]]:
+        """Shared creation flow used by each per-type method."""
+        try:
+            card_id = str(card_id_raw).strip() if card_id_raw is not None else ""
+            if not card_id:
+                return self.error_response("card_id is required")
+
+            if validate_csn:
+                err = self._validate_csn(card_id)
+                if err:
+                    return self.error_response(f"Invalid CSN card_id: {err}")
+
+            if not skip_availability_check:
+                available = await self._check_availability(card_id)
+                if not available:
+                    return self.error_response(f"card_id '{card_id}' is not available (already exists).")
+
+            card_type_type = await self._resolve_type(
+                card_type_id,
+                int(card_type_type_raw) if card_type_type_raw is not None else None
+            )
+
+            extra_payload = extra_payload or {}
+            payload = self._rows_payload(
+                card_id,
+                card_type_id,
+                card_type_type,
+                wiegand_format_id=extra_payload.get("wiegand_format_id"),
+                mobile_opts=extra_payload.get("mobile_opts"),
+                display_card_id=extra_payload.get("display_card_id"),
+            )
+
+            if dry_run:
+                return self.success_response({"dry_run": True, "request_body": payload})
+
+            resp = await self._post_create(payload)
+            if resp.status_code != 200:
+                try:
+                    ej = resp.json()
+                except Exception:
+                    ej = None
+                if ej:
+                    ec = ej.get("error_code") or ej.get("code")
+                    msg = ej.get("message") or resp.text
+                    return self.error_response(f"Failed to create card: {ec or resp.status_code} - {msg}")
+                return self.error_response(f"Failed to create card: {resp.status_code} - {resp.text}")
+
+            create_json = resp.json()
+            result: Dict[str, Any] = {
+                "message": "Card created",
+                "request_body": payload,
+                "response": create_json,
+            }
+
+            if assign_to_user_id is not None:
+                assign_res = await self._assign_to_user(
+                    user_id=str(assign_to_user_id),
+                    create_json=create_json,
+                    card_id=card_id,
+                    card_type_id=card_type_id,
+                    card_type_type=card_type_type,
+                )
+                result["assignment"] = assign_res
+                if not assign_res.get("assigned"):
+                    result["message"] = "Card created, but assignment failed."
+
+            return self.success_response(result)
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    # ──────────────────────────── public tools ────────────────────────────
+    async def get_card_types(self, args: Dict[str, Any]) -> Sequence[Dict[str, Any]]:
+        """Tool: get-card-types"""
+        try:
+            self.check_auth()
+            types_map = await self._get_card_types_map()
+            return self.success_response({"types": types_map})
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def get_wiegand_format_presets(self, args: Dict[str, Any]) -> Sequence[Dict[str, Any]]:
+        """Tool: get-wiegand-format-presets"""
+        try:
+            self.check_auth()
+            return self.success_response({
+                "presets": WIEGAND_PRESETS,
+                "how_to_choose": (
+                    "Choose a format used at your site. For 26bit (H10301), facility_code must be 0–255 and "
+                    "card_number 0–65535. For HID37 (H10302), facility_code 0–65535 and card_number 0–524287. "
+                    "display_card_id must be 'FC-ID' (e.g., '12-3456')."
+                ),
+                "examples": [
+                    {"wiegand_format_id": 0, "facility_code": 12, "card_number": 3456, "display_card_id": "12-3456"},
+                    {"wiegand_format": "HID37", "facility_code": 100, "card_number": 12345, "display_card_id": "100-12345"},
+                ],
+            })
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def check_card_availability(self, args: Dict[str, Any]) -> Sequence[Dict[str, Any]]:
+        """Tool: check-card-availability"""
+        try:
+            self.check_auth()
+            card_id = str(args.get("card_id", "")).strip()
+            if not card_id:
+                return self.error_response("card_id is required")
+            available = await self._check_availability(card_id)
+            return self.success_response({"card_id": card_id, "available": available})
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    # ── Per-type creators (names align with tool names) ───────────────────
+    async def create_card_csn(self, args: Dict[str, Any]) -> Sequence[Dict[str, Any]]:
+        return await self._create_card_flow(
+            card_id_raw=args.get("card_id"),
+            card_type_id=CARD_KIND_TO_ID["CSN"],
+            card_type_type_raw=args.get("card_type_type"),
+            assign_to_user_id=args.get("assign_to_user_id"),
+            skip_availability_check=bool(args.get("skip_availability_check", False)),
+            dry_run=bool(args.get("dry_run", False)),
+            validate_csn=True,
+        )
+
+    async def create_card_wiegand(self, args: Dict[str, Any]) -> Sequence[Dict[str, Any]]:
+        # Resolve wiegand_format_id from alias if needed
+        wf_id = args.get("wiegand_format_id")
+        wf_alias = args.get("wiegand_format")
+        if wf_id is None and wf_alias:
+            wf_id = WIEGAND_FORMAT_ALIAS.get(str(wf_alias).lower())
+
+        if wf_id is None:
+            return self.error_response(
+                "wiegand_format_id is required for Wiegand cards.",
+                {"presets": WIEGAND_PRESETS}
+            )
+
+        # Required by tool schema; double-check & validate ranges
+        facility = args.get("facility_code")
+        number = args.get("card_number")
+        display_override = args.get("display_card_id")
+
+        # card_id must be numeric ASCII digits (no coercion)
+        cid_raw = args.get("card_id")
+        cid = str(cid_raw).strip() if cid_raw is not None else ""
+        if not cid:
+            return self.error_response("card_id is required")
+        if not _ascii_digits(cid):
+            return self.error_response("Wiegand card_id must be numeric (ASCII digits 0-9 only).")
+
+        # Validate facility/card_number + display_card_id consistency & ranges
+        err_details = self._validate_wiegand_values(
+            wf_id=int(wf_id),
+            facility_code=facility,
+            card_number=number,
+            display_card_id=display_override,
+        )
+        if err_details:
+            return self.error_response(
+                "Invalid Wiegand parameters for selected format.",
+                err_details
+            )
+
+        extra: Dict[str, Any] = {"wiegand_format_id": int(wf_id)}
+        if display_override:
+            extra["display_card_id"] = str(display_override)
+        else:
+            # Safe to set display as "FC-ID" derived from user-provided numeric inputs (no mutation)
+            extra["display_card_id"] = f"{int(facility)}-{int(number)}"
+
+        return await self._create_card_flow(
+            card_id_raw=cid,
+            card_type_id=CARD_KIND_TO_ID["WIEGAND"],
+            card_type_type_raw=args.get("card_type_type"),
+            assign_to_user_id=args.get("assign_to_user_id"),
+            skip_availability_check=bool(args.get("skip_availability_check", False)),
+            dry_run=bool(args.get("dry_run", False)),
+            extra_payload=extra,
+        )
+
+    async def create_card_secure_credential(self, args: Dict[str, Any]) -> Sequence[Dict[str, Any]]:
+        return await self._create_card_flow(
+            card_id_raw=args.get("card_id"),
+            card_type_id=CARD_KIND_TO_ID["SECURE_CREDENTIAL"],
+            card_type_type_raw=args.get("card_type_type"),
+            assign_to_user_id=args.get("assign_to_user_id"),
+            skip_availability_check=bool(args.get("skip_availability_check", False)),
+            dry_run=bool(args.get("dry_run", False)),
+        )
+
+    async def create_card_access_on_card(self, args: Dict[str, Any]) -> Sequence[Dict[str, Any]]:
+        return await self._create_card_flow(
+            card_id_raw=args.get("card_id"),
+            card_type_id=CARD_KIND_TO_ID["ACCESS_ON_CARD"],
+            card_type_type_raw=args.get("card_type_type"),
+            assign_to_user_id=args.get("assign_to_user_id"),
+            skip_availability_check=bool(args.get("skip_availability_check", False)),
+            dry_run=bool(args.get("dry_run", False)),
+        )
+
+    async def create_card_mobile_csn(self, args: Dict[str, Any]) -> Sequence[Dict[str, Any]]:
+        mobile_opts = {k: args.get(k) for k in (
+            "isUserPhoto", "isDepartment", "isTitle", "start_datetime", "expiry_datetime", "display_card_id"
+        )}
+        return await self._create_card_flow(
+            card_id_raw=args.get("card_id"),
+            card_type_id=CARD_KIND_TO_ID["MOBILE_CSN"],
+            card_type_type_raw=args.get("card_type_type"),
+            assign_to_user_id=args.get("assign_to_user_id"),
+            skip_availability_check=bool(args.get("skip_availability_check", False)),
+            dry_run=bool(args.get("dry_run", False)),
+            extra_payload={"mobile_opts": mobile_opts},
+        )
+
+    async def create_card_wiegand_mobile(self, args: Dict[str, Any]) -> Sequence[Dict[str, Any]]:
+        wf_id = args.get("wiegand_format_id")
+        wf_alias = args.get("wiegand_format")
+        if wf_id is None and wf_alias:
+            wf_id = WIEGAND_FORMAT_ALIAS.get(str(wf_alias).lower())
+
+        if wf_id is None:
+            return self.error_response(
+                "wiegand_format_id is required for Wiegand Mobile cards.",
+                {"presets": WIEGAND_PRESETS},
+            )
+
+        facility = args.get("facility_code")
+        number = args.get("card_number")
+        display_override = args.get("display_card_id")
+
+        cid_raw = args.get("card_id")
+        cid = str(cid_raw).strip() if cid_raw is not None else ""
+        if not cid:
+            return self.error_response("card_id is required")
+        if not _ascii_digits(cid):
+            return self.error_response("Wiegand Mobile card_id must be numeric (ASCII digits 0-9 only).")
+
+        err_details = self._validate_wiegand_values(
+            wf_id=int(wf_id),
+            facility_code=facility,
+            card_number=number,
+            display_card_id=display_override,
+        )
+        if err_details:
+            return self.error_response(
+                "Invalid Wiegand parameters for selected format.",
+                err_details
+            )
+
+        extra: Dict[str, Any] = {"wiegand_format_id": int(wf_id)}
+        if display_override:
+            extra["display_card_id"] = str(display_override)
+        else:
+            extra["display_card_id"] = f"{int(facility)}-{int(number)}"
+
+        return await self._create_card_flow(
+            card_id_raw=cid,
+            card_type_id=CARD_KIND_TO_ID["WIEGAND_MOBILE"],
+            card_type_type_raw=args.get("card_type_type"),
+            assign_to_user_id=args.get("assign_to_user_id"),
+            skip_availability_check=bool(args.get("skip_availability_check", False)),
+            dry_run=bool(args.get("dry_run", False)),
+            extra_payload=extra,
+        )
+
+    async def create_card_qr_barcode(self, args: Dict[str, Any]) -> Sequence[Dict[str, Any]]:
+        return await self._create_card_flow(
+            card_id_raw=args.get("card_id"),
+            card_type_id=CARD_KIND_TO_ID["QR_BARCODE"],
+            card_type_type_raw=args.get("card_type_type"),
+            assign_to_user_id=args.get("assign_to_user_id"),
+            skip_availability_check=bool(args.get("skip_availability_check", False)),
+            dry_run=bool(args.get("dry_run", False)),
+        )
+
+    async def create_card_biostar2_qr(self, args: Dict[str, Any]) -> Sequence[Dict[str, Any]]:
+        return await self._create_card_flow(
+            card_id_raw=args.get("card_id"),
+            card_type_id=CARD_KIND_TO_ID["BIOSTAR2_QR"],
+            card_type_type_raw=args.get("card_type_type"),
+            assign_to_user_id=args.get("assign_to_user_id"),
+            skip_availability_check=bool(args.get("skip_availability_check", False)),
+            dry_run=bool(args.get("dry_run", False)),
+        )