webpilot-engine 2.0.0__py3-none-any.whl

config/settings.py

@@ -0,0 +1,339 @@
+"""Dedicated centralized configuration and settings module.
+
+Enforces strict resolution precedence:
+1. Environment variables (os.environ)
+2. .env file
+3. Dedicated JSON configuration files (settings.json, device_profile.json)
+
+Zero hardcoded fallbacks in source code: coordinates, IPs, ports, device models,
+and timeouts are exclusively sourced from configuration.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional, Tuple
+
+from exceptions import ConfigurationError
+from models import DeviceProfile, ProxyConfig
+
+# Project root and configuration paths
+PROJECT_ROOT: str = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+CONFIG_DIR: str = os.path.join(PROJECT_ROOT, "config")
+DEFAULT_SETTINGS_JSON: str = os.path.join(CONFIG_DIR, "settings.json")
+DEFAULT_SETTINGS_EXAMPLE_JSON: str = os.path.join(CONFIG_DIR, "settings.example.json")
+DEFAULT_DEVICE_PROFILE_JSON: str = os.path.join(CONFIG_DIR, "device_profile.json")
+DEFAULT_DEVICE_PROFILE_EXAMPLE_JSON: str = os.path.join(CONFIG_DIR, "device_profile.example.json")
+DEFAULT_ENV_FILE: str = os.path.join(PROJECT_ROOT, ".env")
+
+
+def parse_env_file(filepath: str) -> Dict[str, str]:
+    """Parse a .env file into a dictionary without modifying os.environ."""
+    if not os.path.isfile(filepath):
+        return {}
+
+    env_vars: Dict[str, str] = {}
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            for raw_line in f:
+                line = raw_line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                if "=" in line:
+                    k, v = line.split("=", 1)
+                    k = k.strip()
+                    v = v.strip()
+                    # Strip matching surrounding quotes
+                    if len(v) >= 2 and ((v.startswith('"') and v.endswith('"')) or (v.startswith("'") and v.endswith("'"))):
+                        v = v[1:-1]
+                    env_vars[k] = v
+    except Exception as exc:
+        raise ConfigurationError(f"Failed to parse .env file at {filepath}: {exc}") from exc
+
+    return env_vars
+
+
+def load_json_file(primary_path: str, fallback_path: Optional[str] = None) -> Dict[str, Any]:
+    """Loads a JSON configuration file, falling back to a template if primary is absent."""
+    target_path = primary_path
+    if not os.path.isfile(target_path):
+        if fallback_path and os.path.isfile(fallback_path):
+            target_path = fallback_path
+        else:
+            return {}
+
+    try:
+        with open(target_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+            if isinstance(data, dict):
+                return data
+            raise ConfigurationError(f"JSON config at {target_path} must be an object/dict")
+    except Exception as exc:
+        raise ConfigurationError(f"Failed to read JSON config at {target_path}: {exc}") from exc
+
+
+class ValueResolver:
+    """Resolves values following strict precedence: os.environ -> .env -> JSON."""
+
+    def __init__(self, env_data: Dict[str, str], json_data: Dict[str, Any], example_json_data: Dict[str, Any]):
+        self.env_data = env_data
+        self.json_data = json_data
+        self.example_json_data = example_json_data
+
+    def resolve(
+        self,
+        json_key: str,
+        env_var: str,
+        default: Any = None,
+        cast_type: Optional[type] = None
+    ) -> Any:
+        """Resolve a setting by priority."""
+        # 1. os.environ
+        if env_var in os.environ and os.environ[env_var] != "":
+            raw_val = os.environ[env_var]
+            return self._cast(raw_val, cast_type)
+
+        # 2. .env file
+        if env_var in self.env_data and self.env_data[env_var] != "":
+            raw_val = self.env_data[env_var]
+            return self._cast(raw_val, cast_type)
+
+        # 3. Dedicated JSON config
+        if json_key in self.json_data and self.json_data[json_key] is not None:
+            raw_val = self.json_data[json_key]
+            return self._cast(raw_val, cast_type)
+
+        # 4. Dedicated JSON example template
+        if json_key in self.example_json_data and self.example_json_data[json_key] is not None:
+            raw_val = self.example_json_data[json_key]
+            return self._cast(raw_val, cast_type)
+
+        # 5. Default
+        return default
+
+    @staticmethod
+    def _cast(val: Any, cast_type: Optional[type]) -> Any:
+        if cast_type is None or val is None:
+            return val
+        if cast_type == bool:
+            if isinstance(val, bool):
+                return val
+            s = str(val).strip().lower()
+            return s in ("1", "true", "yes", "on", "t")
+        try:
+            return cast_type(val)
+        except (ValueError, TypeError) as exc:
+            raise ConfigurationError(f"Unable to cast value {val!r} to {cast_type.__name__}: {exc}") from exc
+
+
+@dataclass
+class Settings:
+    """Fully resolved runtime configuration."""
+
+    headless: bool
+    default_timeout_ms: int
+    form_ready_timeout_ms: int
+    submission_wait_ms: int
+    expand_section_wait_ms: int
+    screenshots_dir: str
+    cookies_path: Optional[str]
+    data_path: Optional[str]
+    settings_path: str
+    device_profile_path: str
+    proxy: Optional[ProxyConfig] = None
+    geolocation_latitude: Optional[float] = None
+    geolocation_longitude: Optional[float] = None
+    geolocation_accuracy: Optional[float] = None
+
+
+_SETTINGS_CACHE: Optional[Settings] = None
+_DEVICE_PROFILE_CACHE: Optional[DeviceProfile] = None
+
+
+def reset_settings_cache() -> None:
+    """Clear cached settings and device profile singletons."""
+    global _SETTINGS_CACHE, _DEVICE_PROFILE_CACHE
+    _SETTINGS_CACHE = None
+    _DEVICE_PROFILE_CACHE = None
+
+
+def get_settings(
+    env_file: Optional[str] = None,
+    settings_json_path: Optional[str] = None,
+    reload: bool = False
+) -> Settings:
+    """Build or retrieve the resolved Settings singleton."""
+    global _SETTINGS_CACHE
+    if _SETTINGS_CACHE is not None and not reload:
+        return _SETTINGS_CACHE
+
+    target_env = env_file or os.environ.get("APP_ENV_FILE") or DEFAULT_ENV_FILE
+    env_data = parse_env_file(target_env)
+
+    target_settings_path = (
+        settings_json_path
+        or os.environ.get("APP_SETTINGS_PATH")
+        or env_data.get("APP_SETTINGS_PATH")
+        or DEFAULT_SETTINGS_JSON
+    )
+
+    json_data = load_json_file(target_settings_path, DEFAULT_SETTINGS_EXAMPLE_JSON)
+    example_json_data = load_json_file(DEFAULT_SETTINGS_EXAMPLE_JSON)
+
+    resolver = ValueResolver(env_data, json_data, example_json_data)
+
+    # Proxy resolution
+    proxy_server = resolver.resolve("proxy_server", "APP_PROXY_SERVER", cast_type=str)
+    if not proxy_server and isinstance(json_data.get("proxy"), dict):
+        proxy_server = json_data["proxy"].get("server")
+    proxy_user = resolver.resolve("proxy_username", "APP_PROXY_USERNAME", cast_type=str)
+    if not proxy_user and isinstance(json_data.get("proxy"), dict):
+        proxy_user = json_data["proxy"].get("username")
+    proxy_pass = resolver.resolve("proxy_password", "APP_PROXY_PASSWORD", cast_type=str)
+    if not proxy_pass and isinstance(json_data.get("proxy"), dict):
+        proxy_pass = json_data["proxy"].get("password")
+
+    proxy_cfg = ProxyConfig(server=proxy_server, username=proxy_user, password=proxy_pass) if proxy_server else None
+
+    # Geolocation resolution
+    geo_lat = resolver.resolve("geolocation_latitude", "APP_GEOLOCATION_LATITUDE", cast_type=float)
+    if geo_lat is None and isinstance(json_data.get("geolocation"), dict):
+        geo_lat = json_data["geolocation"].get("latitude")
+    geo_lon = resolver.resolve("geolocation_longitude", "APP_GEOLOCATION_LONGITUDE", cast_type=float)
+    if geo_lon is None and isinstance(json_data.get("geolocation"), dict):
+        geo_lon = json_data["geolocation"].get("longitude")
+    geo_acc = resolver.resolve("geolocation_accuracy", "APP_GEOLOCATION_ACCURACY", default=10.0, cast_type=float)
+    if geo_acc is None and isinstance(json_data.get("geolocation"), dict):
+        geo_acc = json_data["geolocation"].get("accuracy", 10.0)
+
+    # Device profile path
+    dev_path = resolver.resolve(
+        "device_profile_path",
+        "APP_DEVICE_PROFILE_PATH",
+        default=DEFAULT_DEVICE_PROFILE_JSON,
+        cast_type=str
+    )
+
+    settings = Settings(
+        headless=resolver.resolve("headless", "APP_HEADLESS", default=True, cast_type=bool),
+        default_timeout_ms=resolver.resolve("default_timeout_ms", "APP_DEFAULT_TIMEOUT_MS", default=45000, cast_type=int),
+        form_ready_timeout_ms=resolver.resolve("form_ready_timeout_ms", "APP_FORM_READY_TIMEOUT_MS", default=10000, cast_type=int),
+        submission_wait_ms=resolver.resolve("submission_wait_ms", "APP_SUBMISSION_WAIT_MS", default=8000, cast_type=int),
+        expand_section_wait_ms=resolver.resolve("expand_section_wait_ms", "APP_EXPAND_SECTION_WAIT_MS", default=800, cast_type=int),
+        screenshots_dir=resolver.resolve("screenshots_dir", "APP_SCREENSHOTS_DIR", default="screenshots", cast_type=str),
+        cookies_path=resolver.resolve("cookies_path", "APP_COOKIES_PATH", cast_type=str),
+        data_path=resolver.resolve("data_path", "APP_DATA_PATH", default=None, cast_type=str),
+        settings_path=target_settings_path,
+        device_profile_path=dev_path,
+        proxy=proxy_cfg,
+        geolocation_latitude=float(geo_lat) if geo_lat is not None else None,
+        geolocation_longitude=float(geo_lon) if geo_lon is not None else None,
+        geolocation_accuracy=float(geo_acc) if geo_acc is not None else None,
+    )
+
+    _SETTINGS_CACHE = settings
+    return settings
+
+
+def load_device_profile(
+    profile_path: Optional[str] = None,
+    env_file: Optional[str] = None,
+    reload: bool = False
+) -> DeviceProfile:
+    """Loads and resolves DeviceProfile adhering strictly to 3-tier precedence.
+
+    Order:
+    1. os.environ
+    2. .env file
+    3. Dedicated JSON file (device_profile.json or device_profile.example.json)
+    """
+    global _DEVICE_PROFILE_CACHE
+    if _DEVICE_PROFILE_CACHE is not None and not reload and profile_path is None:
+        return _DEVICE_PROFILE_CACHE
+
+    target_env = env_file or os.environ.get("APP_ENV_FILE") or DEFAULT_ENV_FILE
+    env_data = parse_env_file(target_env)
+
+    if profile_path is not None:
+        if not os.path.isfile(profile_path):
+            raise ConfigurationError(f"Specified device profile file not found: '{profile_path}'")
+        target_file = profile_path
+        example_fallback = None
+    else:
+        target_file = (
+            os.environ.get("APP_DEVICE_PROFILE_PATH")
+            or env_data.get("APP_DEVICE_PROFILE_PATH")
+            or DEFAULT_DEVICE_PROFILE_JSON
+        )
+        example_fallback = DEFAULT_DEVICE_PROFILE_EXAMPLE_JSON
+
+    json_data = load_json_file(target_file, example_fallback)
+    example_data = load_json_file(example_fallback) if example_fallback else {}
+
+    if not json_data and not example_data:
+        raise ConfigurationError(
+            f"Device profile configuration not found at '{target_file}'"
+        )
+
+    resolver = ValueResolver(env_data, json_data, example_data)
+
+    # Resolve viewport
+    vp_w = resolver.resolve("viewport_width", "DEVICE_VIEWPORT_WIDTH", cast_type=int)
+    if vp_w is None and isinstance(json_data.get("viewport"), dict):
+        vp_w = json_data["viewport"].get("width")
+    if vp_w is None and isinstance(example_data.get("viewport"), dict):
+        vp_w = example_data["viewport"].get("width")
+
+    vp_h = resolver.resolve("viewport_height", "DEVICE_VIEWPORT_HEIGHT", cast_type=int)
+    if vp_h is None and isinstance(json_data.get("viewport"), dict):
+        vp_h = json_data["viewport"].get("height")
+    if vp_h is None and isinstance(example_data.get("viewport"), dict):
+        vp_h = example_data["viewport"].get("height")
+
+    # Resolve geolocation
+    geo_lat = resolver.resolve("geolocation_latitude", "DEVICE_GEOLOCATION_LATITUDE", cast_type=float)
+    if geo_lat is None and isinstance(json_data.get("geolocation"), dict):
+        geo_lat = json_data["geolocation"].get("latitude")
+    geo_lon = resolver.resolve("geolocation_longitude", "DEVICE_GEOLOCATION_LONGITUDE", cast_type=float)
+    if geo_lon is None and isinstance(json_data.get("geolocation"), dict):
+        geo_lon = json_data["geolocation"].get("longitude")
+    geo_acc = resolver.resolve("geolocation_accuracy", "DEVICE_GEOLOCATION_ACCURACY", cast_type=float)
+    if geo_acc is None and isinstance(json_data.get("geolocation"), dict):
+        geo_acc = json_data["geolocation"].get("accuracy")
+
+    # Required attributes check: must exist in profile configuration
+    device_name = resolver.resolve("device_name", "DEVICE_NAME", cast_type=str)
+    user_agent = resolver.resolve("user_agent", "DEVICE_USER_AGENT", cast_type=str)
+
+    if not user_agent:
+        raise ConfigurationError(
+            f"Required 'user_agent' could not be resolved from environment or profile at {target_file}"
+        )
+    if not vp_w or not vp_h:
+        raise ConfigurationError(
+            f"Required viewport dimensions (width, height) missing in configuration at {target_file}"
+        )
+
+    profile = DeviceProfile(
+        device_name=str(device_name or "Standard Profile"),
+        user_agent=str(user_agent),
+        viewport_width=int(vp_w),
+        viewport_height=int(vp_h),
+        device_scale_factor=resolver.resolve("device_scale_factor", "DEVICE_SCALE_FACTOR", default=1.0, cast_type=float),
+        is_mobile=resolver.resolve("is_mobile", "DEVICE_IS_MOBILE", default=False, cast_type=bool),
+        has_touch=resolver.resolve("has_touch", "DEVICE_HAS_TOUCH", default=False, cast_type=bool),
+        locale=resolver.resolve("locale", "DEVICE_LOCALE", default="en-US", cast_type=str),
+        timezone_id=resolver.resolve("timezone_id", "DEVICE_TIMEZONE", default="UTC", cast_type=str),
+        geolocation_latitude=float(geo_lat) if geo_lat is not None else None,
+        geolocation_longitude=float(geo_lon) if geo_lon is not None else None,
+        geolocation_accuracy=float(geo_acc) if geo_acc is not None else None,
+        permissions=list(resolver.resolve("permissions", "DEVICE_PERMISSIONS", default=[])),
+        platform=resolver.resolve("platform", "DEVICE_PLATFORM", default="Win32", cast_type=str),
+        vendor=resolver.resolve("vendor", "DEVICE_VENDOR", default="Google Inc.", cast_type=str),
+    )
+
+    if profile_path is None:
+        _DEVICE_PROFILE_CACHE = profile
+    return profile

constants/__init__.py

@@ -0,0 +1,165 @@
+"""Constants package for universal web applier."""
+
+from constants.timeouts import (
+    DEFAULT_NAV_TIMEOUT_MS,
+    DEFAULT_FORM_READY_TIMEOUT_MS,
+    DEFAULT_SUBMIT_WAIT_MS,
+    DEFAULT_EXPAND_SECTION_WAIT_MS,
+    PAUSE_DOM_CONTENT_LOADED_MS,
+    PAUSE_PORTAL_DROPDOWN_CLICK_MS,
+    PAUSE_PORTAL_APPLY_CLICK_MS,
+    PAUSE_LOGIN_STABILIZATION_MS,
+    PAUSE_INPUT_SET_MS,
+    PAUSE_RETRY_FALLBACK_MS,
+    PAUSE_PICKLIST_EXPAND_MS,
+    PAUSE_PICKLIST_SCROLL_STEP_MS,
+    PAUSE_PICKLIST_CLOSE_MS,
+    PAUSE_UPLOAD_DIRECT_MS,
+    PAUSE_UPLOAD_CHOOSER_MS,
+    PAUSE_REACTIVE_STABILIZE_MS,
+    PAUSE_MICRO_WAIT_MS,
+    PAUSE_MODAL_DISMISS_MS,
+)
+from constants.selectors import (
+    SELECTOR_SECTION_BUTTON,
+    SELECTOR_SECTION_CONTAINER,
+    SELECTOR_SECTION_CONTENT,
+    SELECTOR_PORTAL_DROPDOWN,
+    SELECTOR_PORTAL_APPLY_BUTTON,
+    SELECTOR_FILE_INPUT_GENERIC,
+    SELECTOR_CUSTOM_UPLOAD_TRIGGERS,
+    SELECTOR_PICKLIST_INPUTS,
+    SELECTOR_MODAL_DIALOGS,
+    SELECTOR_VALIDATION_ERRORS,
+)
+from constants.contracts import (
+    SCHEMA_KEY_TITLE,
+    SCHEMA_KEY_URL,
+    SCHEMA_KEY_SECTIONS,
+    SCHEMA_KEY_INPUTS,
+    SCHEMA_KEY_DROPDOWNS,
+    SCHEMA_KEY_CHOICES,
+    SCHEMA_KEY_FILE_UPLOADS,
+    SCHEMA_KEY_ALREADY_UPLOADED,
+    SCHEMA_KEY_BUTTONS,
+    FIELD_KEY_ID,
+    FIELD_KEY_LABEL,
+    FIELD_KEY_TYPE,
+    FIELD_KEY_REQUIRED,
+    FIELD_KEY_VALUE,
+    FIELD_KEY_TRIGGER_ID,
+    FIELD_KEY_SAMPLE_OPTIONS,
+    FIELD_KEY_OPTIONS_COUNT,
+    CHOICE_KEY_QUESTION,
+    CHOICE_KEY_TYPE,
+    CHOICE_KEY_REQUIRED,
+    CHOICE_KEY_OPTIONS,
+    CHOICE_KEY_SELECTED,
+    BUTTON_KEY_ID,
+    BUTTON_KEY_TEXT,
+    BUTTON_KEY_ACTION,
+    WIDGET_TYPE_TEXT,
+    WIDGET_TYPE_SELECT,
+    WIDGET_TYPE_PICKLIST,
+    WIDGET_TYPE_RADIO,
+    WIDGET_TYPE_CHECKBOX,
+    WIDGET_TYPE_CUSTOM_RADIO,
+    WIDGET_TYPE_BUTTON,
+    BUTTON_ACTION_DEFAULT,
+    OUTCOME_KEY_SUCCESS,
+    OUTCOME_KEY_TARGET,
+    OUTCOME_KEY_REDIRECTED,
+    OUTCOME_KEY_NEW_WINDOW,
+    OUTCOME_KEY_NEW_URL,
+    OUTCOME_KEY_MODAL_OPENED,
+    OUTCOME_KEY_MODAL_TEXT,
+    OUTCOME_KEY_NEW_INPUTS_COUNT,
+    OUTCOME_KEY_SCHEMA,
+    OUTCOME_KEY_ALERTS,
+    SUMMARY_KEY_CONFIRMED,
+    SUMMARY_KEY_UNCONFIRMED,
+    SUMMARY_KEY_FAILED,
+    SCHEMA_KEYS,
+    OUTCOME_KEYS,
+    SUMMARY_KEYS,
+)
+
+__all__ = [
+    "DEFAULT_NAV_TIMEOUT_MS",
+    "DEFAULT_FORM_READY_TIMEOUT_MS",
+    "DEFAULT_SUBMIT_WAIT_MS",
+    "DEFAULT_EXPAND_SECTION_WAIT_MS",
+    "PAUSE_DOM_CONTENT_LOADED_MS",
+    "PAUSE_PORTAL_DROPDOWN_CLICK_MS",
+    "PAUSE_PORTAL_APPLY_CLICK_MS",
+    "PAUSE_LOGIN_STABILIZATION_MS",
+    "PAUSE_INPUT_SET_MS",
+    "PAUSE_RETRY_FALLBACK_MS",
+    "PAUSE_PICKLIST_EXPAND_MS",
+    "PAUSE_PICKLIST_SCROLL_STEP_MS",
+    "PAUSE_PICKLIST_CLOSE_MS",
+    "PAUSE_UPLOAD_DIRECT_MS",
+    "PAUSE_UPLOAD_CHOOSER_MS",
+    "PAUSE_REACTIVE_STABILIZE_MS",
+    "PAUSE_MICRO_WAIT_MS",
+    "PAUSE_MODAL_DISMISS_MS",
+    "SELECTOR_SECTION_BUTTON",
+    "SELECTOR_SECTION_CONTAINER",
+    "SELECTOR_SECTION_CONTENT",
+    "SELECTOR_PORTAL_DROPDOWN",
+    "SELECTOR_PORTAL_APPLY_BUTTON",
+    "SELECTOR_FILE_INPUT_GENERIC",
+    "SELECTOR_CUSTOM_UPLOAD_TRIGGERS",
+    "SELECTOR_PICKLIST_INPUTS",
+    "SELECTOR_MODAL_DIALOGS",
+    "SELECTOR_VALIDATION_ERRORS",
+    "SCHEMA_KEY_TITLE",
+    "SCHEMA_KEY_URL",
+    "SCHEMA_KEY_SECTIONS",
+    "SCHEMA_KEY_INPUTS",
+    "SCHEMA_KEY_DROPDOWNS",
+    "SCHEMA_KEY_CHOICES",
+    "SCHEMA_KEY_FILE_UPLOADS",
+    "SCHEMA_KEY_ALREADY_UPLOADED",
+    "SCHEMA_KEY_BUTTONS",
+    "FIELD_KEY_ID",
+    "FIELD_KEY_LABEL",
+    "FIELD_KEY_TYPE",
+    "FIELD_KEY_REQUIRED",
+    "FIELD_KEY_VALUE",
+    "FIELD_KEY_TRIGGER_ID",
+    "FIELD_KEY_SAMPLE_OPTIONS",
+    "FIELD_KEY_OPTIONS_COUNT",
+    "CHOICE_KEY_QUESTION",
+    "CHOICE_KEY_TYPE",
+    "CHOICE_KEY_REQUIRED",
+    "CHOICE_KEY_OPTIONS",
+    "CHOICE_KEY_SELECTED",
+    "BUTTON_KEY_ID",
+    "BUTTON_KEY_TEXT",
+    "BUTTON_KEY_ACTION",
+    "WIDGET_TYPE_TEXT",
+    "WIDGET_TYPE_SELECT",
+    "WIDGET_TYPE_PICKLIST",
+    "WIDGET_TYPE_RADIO",
+    "WIDGET_TYPE_CHECKBOX",
+    "WIDGET_TYPE_CUSTOM_RADIO",
+    "WIDGET_TYPE_BUTTON",
+    "BUTTON_ACTION_DEFAULT",
+    "OUTCOME_KEY_SUCCESS",
+    "OUTCOME_KEY_TARGET",
+    "OUTCOME_KEY_REDIRECTED",
+    "OUTCOME_KEY_NEW_WINDOW",
+    "OUTCOME_KEY_NEW_URL",
+    "OUTCOME_KEY_MODAL_OPENED",
+    "OUTCOME_KEY_MODAL_TEXT",
+    "OUTCOME_KEY_NEW_INPUTS_COUNT",
+    "OUTCOME_KEY_SCHEMA",
+    "OUTCOME_KEY_ALERTS",
+    "SUMMARY_KEY_CONFIRMED",
+    "SUMMARY_KEY_UNCONFIRMED",
+    "SUMMARY_KEY_FAILED",
+    "SCHEMA_KEYS",
+    "OUTCOME_KEYS",
+    "SUMMARY_KEYS",
+]

constants/contracts.py

@@ -0,0 +1,95 @@
+"""Single Source of Truth (SSOT) for data contracts, schema keys, and wire models."""
+
+from typing import Final
+
+# --- Inspection Schema Contract Keys ---
+SCHEMA_KEY_TITLE: Final[str] = "title"
+SCHEMA_KEY_URL: Final[str] = "url"
+SCHEMA_KEY_SECTIONS: Final[str] = "sections"
+SCHEMA_KEY_INPUTS: Final[str] = "inputs"
+SCHEMA_KEY_DROPDOWNS: Final[str] = "dropdowns"
+SCHEMA_KEY_CHOICES: Final[str] = "choices"
+SCHEMA_KEY_FILE_UPLOADS: Final[str] = "file_uploads"
+SCHEMA_KEY_ALREADY_UPLOADED: Final[str] = "already_uploaded_files"
+SCHEMA_KEY_BUTTONS: Final[str] = "buttons"
+
+# --- Field / Element Property Keys ---
+FIELD_KEY_ID: Final[str] = "id"
+FIELD_KEY_LABEL: Final[str] = "label"
+FIELD_KEY_TYPE: Final[str] = "type"
+FIELD_KEY_REQUIRED: Final[str] = "required"
+FIELD_KEY_VALUE: Final[str] = "value"
+FIELD_KEY_TRIGGER_ID: Final[str] = "trigger_id"
+FIELD_KEY_SAMPLE_OPTIONS: Final[str] = "sample_options"
+FIELD_KEY_OPTIONS_COUNT: Final[str] = "options_count"
+
+# --- Choice Group Property Keys ---
+CHOICE_KEY_QUESTION: Final[str] = "question"
+CHOICE_KEY_TYPE: Final[str] = "type"
+CHOICE_KEY_REQUIRED: Final[str] = "required"
+CHOICE_KEY_OPTIONS: Final[str] = "options"
+CHOICE_KEY_SELECTED: Final[str] = "selected"
+
+# --- Action Button Property Keys ---
+BUTTON_KEY_ID: Final[str] = "id"
+BUTTON_KEY_TEXT: Final[str] = "text"
+BUTTON_KEY_ACTION: Final[str] = "action"
+
+# --- Widget Type Identifiers ---
+WIDGET_TYPE_TEXT: Final[str] = "text"
+WIDGET_TYPE_SELECT: Final[str] = "select"
+WIDGET_TYPE_PICKLIST: Final[str] = "picklist"
+WIDGET_TYPE_RADIO: Final[str] = "radio"
+WIDGET_TYPE_CHECKBOX: Final[str] = "checkbox"
+WIDGET_TYPE_CUSTOM_RADIO: Final[str] = "custom_radio"
+WIDGET_TYPE_BUTTON: Final[str] = "button"
+BUTTON_ACTION_DEFAULT: Final[str] = "action"
+
+# --- Reactive Action Outcome Keys ---
+OUTCOME_KEY_SUCCESS: Final[str] = "success"
+OUTCOME_KEY_TARGET: Final[str] = "target"
+OUTCOME_KEY_REDIRECTED: Final[str] = "redirected"
+OUTCOME_KEY_NEW_WINDOW: Final[str] = "new_window"
+OUTCOME_KEY_NEW_URL: Final[str] = "new_url"
+OUTCOME_KEY_MODAL_OPENED: Final[str] = "modal_opened"
+OUTCOME_KEY_MODAL_TEXT: Final[str] = "modal_text"
+OUTCOME_KEY_NEW_INPUTS_COUNT: Final[str] = "new_inputs_count"
+OUTCOME_KEY_SCHEMA: Final[str] = "schema"
+OUTCOME_KEY_ALERTS: Final[str] = "alerts"
+
+# --- Fill Summary Keys ---
+SUMMARY_KEY_CONFIRMED: Final[str] = "confirmed"
+SUMMARY_KEY_UNCONFIRMED: Final[str] = "unconfirmed"
+SUMMARY_KEY_FAILED: Final[str] = "failed"
+
+# --- Contract Key Sets ---
+SCHEMA_KEYS: Final[set] = {
+    SCHEMA_KEY_TITLE,
+    SCHEMA_KEY_URL,
+    SCHEMA_KEY_SECTIONS,
+    SCHEMA_KEY_INPUTS,
+    SCHEMA_KEY_DROPDOWNS,
+    SCHEMA_KEY_CHOICES,
+    SCHEMA_KEY_FILE_UPLOADS,
+    SCHEMA_KEY_ALREADY_UPLOADED,
+    SCHEMA_KEY_BUTTONS,
+}
+
+OUTCOME_KEYS: Final[set] = {
+    OUTCOME_KEY_SUCCESS,
+    OUTCOME_KEY_TARGET,
+    OUTCOME_KEY_REDIRECTED,
+    OUTCOME_KEY_NEW_WINDOW,
+    OUTCOME_KEY_NEW_URL,
+    OUTCOME_KEY_MODAL_OPENED,
+    OUTCOME_KEY_MODAL_TEXT,
+    OUTCOME_KEY_NEW_INPUTS_COUNT,
+    OUTCOME_KEY_SCHEMA,
+    OUTCOME_KEY_ALERTS,
+}
+
+SUMMARY_KEYS: Final[set] = {
+    SUMMARY_KEY_CONFIRMED,
+    SUMMARY_KEY_UNCONFIRMED,
+    SUMMARY_KEY_FAILED,
+}

constants/selectors.py

@@ -0,0 +1,27 @@
+"""CSS and XPath selector constants for form elements and framework widgets."""
+
+from typing import Final
+
+# Form section and accordion toggle selectors
+SELECTOR_SECTION_BUTTON: Final[str] = "button.rcmFormSectionTopBar, .rcmFormSectionTopBar"
+SELECTOR_SECTION_CONTAINER: Final[str] = ".rcmFormSection, [class*='rcmFormSection']"
+SELECTOR_SECTION_CONTENT: Final[str] = ".sectionContent, [class*='sectionContent']"
+
+# Job portal landing transition selectors
+SELECTOR_PORTAL_DROPDOWN: Final[str] = "button.dropdown-toggle, .dropdown-toggle, [data-toggle='dropdown']"
+SELECTOR_PORTAL_APPLY_BUTTON: Final[str] = ".dialogApplyBtn"
+
+# File input and upload trigger selectors
+SELECTOR_FILE_INPUT_GENERIC: Final[str] = "input[type='file']"
+SELECTOR_CUSTOM_UPLOAD_TRIGGERS: Final[str] = (
+    "input[type='file'], .sfFileUpload, .fileUploadWrapper, [role='button'][id*='_attach']"
+)
+
+# Enterprise picklist / Combobox selectors
+SELECTOR_PICKLIST_INPUTS: Final[str] = "input[role='combobox'], input[id$=':_input']"
+SELECTOR_MODAL_DIALOGS: Final[str] = ".modal:visible, [role='dialog']:visible, .dialog:visible, .pop-up:visible"
+
+# Error banners and validation notice selectors
+SELECTOR_VALIDATION_ERRORS: Final[str] = (
+    ".alert-danger, .error, .errorMessage, .sf-error, [role='alert'], .validation-summary-errors, .has-error"
+)

constants/timeouts.py

@@ -0,0 +1,25 @@
+"""Timing and delay constants for browser actions and stabilization."""
+
+from typing import Final
+
+# Default timeouts in milliseconds
+DEFAULT_NAV_TIMEOUT_MS: Final[int] = 45000
+DEFAULT_FORM_READY_TIMEOUT_MS: Final[int] = 10000
+DEFAULT_SUBMIT_WAIT_MS: Final[int] = 8000
+DEFAULT_EXPAND_SECTION_WAIT_MS: Final[int] = 800
+
+# Granular stabilization pauses in milliseconds
+PAUSE_DOM_CONTENT_LOADED_MS: Final[int] = 3000
+PAUSE_PORTAL_DROPDOWN_CLICK_MS: Final[int] = 1000
+PAUSE_PORTAL_APPLY_CLICK_MS: Final[int] = 7000
+PAUSE_LOGIN_STABILIZATION_MS: Final[int] = 6000
+PAUSE_INPUT_SET_MS: Final[int] = 150
+PAUSE_RETRY_FALLBACK_MS: Final[int] = 200
+PAUSE_PICKLIST_EXPAND_MS: Final[int] = 400
+PAUSE_PICKLIST_SCROLL_STEP_MS: Final[int] = 450
+PAUSE_PICKLIST_CLOSE_MS: Final[int] = 100
+PAUSE_UPLOAD_DIRECT_MS: Final[int] = 3000
+PAUSE_UPLOAD_CHOOSER_MS: Final[int] = 4000
+PAUSE_REACTIVE_STABILIZE_MS: Final[int] = 3000
+PAUSE_MICRO_WAIT_MS: Final[int] = 100
+PAUSE_MODAL_DISMISS_MS: Final[int] = 200