api.py

"""DatabunkerPro API Client"""

import json
import re
from datetime import datetime
from typing import Any, Dict, Iterable, List, Mapping, Optional, TypedDict, Union, cast

import requests


# Type definitions for better type safety and documentation
class UserOptions(TypedDict, total=False):
    """Options for user operations."""

    groupname: Optional[Union[str, int]]
    groupid: Optional[int]
    rolename: Optional[Union[str, int]]
    roleid: Optional[int]
    slidingtime: Optional[str]
    finaltime: Optional[str]


class LegalBasisOptions(TypedDict, total=False):
    """Options for legal basis operations."""

    brief: str
    status: Optional[str]
    module: Optional[str]
    fulldesc: Optional[str]
    shortdesc: Optional[str]
    basistype: Optional[str]
    requiredmsg: Optional[str]
    requiredflag: Optional[bool]


class LegalBasisUpdateOptions(TypedDict, total=False):
    """Options for legal basis update operations."""

    status: Optional[str]
    module: Optional[str]
    fulldesc: Optional[str]
    shortdesc: Optional[str]
    basistype: Optional[str]
    requiredmsg: Optional[str]
    requiredflag: Optional[bool]


class AgreementAcceptOptions(TypedDict, total=False):
    """Options for agreement acceptance."""

    agreementmethod: Optional[str]
    referencecode: Optional[str]
    starttime: Optional[str]
    finaltime: Optional[str]
    status: Optional[str]
    lastmodifiedby: Optional[str]


class GroupOptions(TypedDict, total=False):
    """Options for group operations."""

    groupname: str
    grouptype: Optional[str]
    groupdesc: Optional[str]


class RoleOptions(TypedDict, total=False):
    """Options for role operations."""

    rolename: str
    roledesc: Optional[str]


class TenantOptions(TypedDict, total=False):
    """Options for tenant operations."""

    tenantname: str
    tenantorg: str
    email: str


class ProcessingActivityOptions(TypedDict, total=False):
    """Options for processing activity operations."""

    activity: str
    title: Optional[str]
    script: Optional[str]
    fulldesc: Optional[str]
    applicableto: Optional[str]


class ProcessingActivityUpdateOptions(TypedDict, total=False):
    """Options for processing activity update operations."""

    newactivity: Optional[str]
    title: Optional[str]
    script: Optional[str]
    fulldesc: Optional[str]
    applicableto: Optional[str]


class SharedRecordOptions(TypedDict, total=False):
    """Options for shared record operations."""

    fields: Optional[
        str
    ]  # A string containing names of fields to share separated by commas
    partner: Optional[
        str
    ]  # It is used as a reference to partner name. It is not enforced.
    appname: Optional[
        str
    ]  # If defined, shows fields from the user app record instead of user profile
    finaltime: Optional[str]  # Expiration time for the shared record


class BasicOptions(TypedDict, total=False):
    """Basic options for operations."""

    finaltime: Optional[str]
    slidingtime: Optional[str]


class FileOptions(TypedDict, total=False):
    """Options for storing a file."""

    mimetype: Optional[str]
    tags: Optional[Union[List[str], str]]
    finaltime: Optional[str]
    slidingtime: Optional[str]


class TokenOptions(TypedDict, total=False):
    """Options for token operations."""

    unique: Optional[bool]
    slidingtime: Optional[str]
    finaltime: Optional[str]


class PolicyOptions(TypedDict, total=False):
    """Options for policy operations."""

    policyname: str
    policydesc: Optional[str]
    policy: Any


class PolicyUpdateOptions(TypedDict, total=False):
    """Options for policy update operations."""

    policyname: Optional[str]
    policydesc: Optional[str]
    policy: Any


class PatchOperation(TypedDict, total=False):
    """Represents a patch operation for user data."""

    op: str  # Operation type (e.g., 'add', 'replace', 'remove')
    path: str  # JSON path to the field to modify
    value: Optional[Any]  # New value for the field


def _add_options(
    data: Dict[str, Any], options: Optional[Mapping[str, Any]], keys: Iterable[str]
) -> Dict[str, Any]:
    """Copy the supplied `keys` from `options` into `data`, skipping unset ones.

    An option the caller left out must stay out of the request body. Python's None
    serializes to JSON null, and the server treats a null as a supplied value: it
    validates `appname: null` and rejects it, and it panics on `requiredflag: null`.
    Other language SDKs avoid this for free — JSON.stringify drops undefined — so
    the guard has to be explicit here.
    """
    for key in keys:
        value = options.get(key) if options else None
        if value is not None:
            data[key] = value
    return data


class DatabunkerproAPI:
    """Main client class for interacting with the DatabunkerPro API."""

    def __init__(
        self, base_url: str, x_bunker_token: str = "", x_bunker_tenant: str = ""
    ):
        """Initialize the DatabunkerPro API client."""
        self.base_url = base_url.rstrip("/")
        self.x_bunker_token = x_bunker_token
        self.x_bunker_tenant = x_bunker_tenant

    def _make_request(
        self,
        endpoint: str,
        data: Optional[Dict[str, Any]] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Make a request to the DatabunkerPro API."""
        headers = {"Content-Type": "application/json"}
        if self.x_bunker_token:
            headers["X-Bunker-Token"] = self.x_bunker_token
        if self.x_bunker_tenant:
            headers["X-Bunker-Tenant"] = self.x_bunker_tenant

        url = f"{self.base_url}/v2/{endpoint}"
        if data or request_metadata:
            body_data = data.copy() if data else {}
            if request_metadata:
                body_data["request_metadata"] = request_metadata
            body = json.dumps(body_data)
        else:
            body = None

        try:
            response = requests.post(url, headers=headers, data=body)
            result: Dict[str, Any] = response.json()

            if not response.ok:
                if result.get("status"):
                    return result
                else:
                    return {
                        "status": "error",
                        "message": result.get("message", "API request failed"),
                    }
            return result
        except requests.exceptions.RequestException as e:
            return {"status": "error", "message": f"Error making request: {str(e)}"}

    def raw_request(
        self,
        endpoint: str,
        data: Optional[Dict[str, Any]] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> bytes:
        """Make a raw request to the DatabunkerPro API and return the response content."""
        headers = {"Content-Type": "application/json"}
        if self.x_bunker_token:
            headers["X-Bunker-Token"] = self.x_bunker_token
        if self.x_bunker_tenant:
            headers["X-Bunker-Tenant"] = self.x_bunker_tenant
        url = f"{self.base_url}/v2/{endpoint}"
        if data or request_metadata:
            body_data = data.copy() if data else {}
            if request_metadata:
                body_data["request_metadata"] = request_metadata
            body = json.dumps(body_data)
        else:
            body = None
        response = requests.post(url, headers=headers, data=body)
        return response.content

    # User Management
    def create_user(
        self,
        profile: Dict[str, Any],
        options: Optional[UserOptions] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Create a new user in DatabunkerPro."""
        data: Dict[str, Any] = {"profile": profile}
        if options:
            # Handle groupname/groupid
            if "groupname" in options and options["groupname"] is not None:
                if str(options["groupname"]).isdigit():
                    data["groupid"] = int(options["groupname"])
                else:
                    data["groupname"] = options["groupname"]
            elif "groupid" in options and options["groupid"] is not None:
                data["groupid"] = int(options["groupid"])
            # Handle rolename/roleid
            if "rolename" in options and options["rolename"] is not None:
                if str(options["rolename"]).isdigit():
                    data["roleid"] = int(options["rolename"])
                else:
                    data["rolename"] = options["rolename"]
            elif "roleid" in options and options["roleid"] is not None:
                data["roleid"] = int(options["roleid"])
            # Handle time parameters
            if "slidingtime" in options:
                data["slidingtime"] = options["slidingtime"]
            if "finaltime" in options:
                data["finaltime"] = options["finaltime"]
        return self._make_request("UserCreate", data, request_metadata)

    def create_users_bulk(
        self,
        records: List[Dict[str, Any]],
        options: Optional[BasicOptions] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """
        Creates multiple users in bulk with their profiles and group information.

        Args:
            records: Array of user records to create
            options: Global options for all users
            request_metadata: Additional metadata to include with the request

        Returns:
            The created users information

        Example:
            # Create multiple users with global time settings
            users = api.create_users_bulk([
                {
                    "profile": {"email": "user1@example.com", "name": "User One"},
                    "groupname": "premium"
                },
                {
                    "profile": {"email": "user2@example.com", "name": "User Two"},
                    "groupid": 123
                }
            ], {
                "finaltime": "100d",
                "slidingtime": "30d"
            })
        """
        data: Dict[str, Any] = {
            "records": [
                {
                    "profile": record["profile"],
                    **(
                        {"groupid": int(record["groupname"])}
                        if "groupname" in record
                        and record["groupname"] is not None
                        and str(record["groupname"]).isdigit()
                        else (
                            {"groupname": record["groupname"]}
                            if "groupname" in record and record["groupname"] is not None
                            else {}
                        )
                    ),
                    **(
                        {"groupid": int(record["groupid"])}
                        if "groupid" in record and record["groupid"] is not None
                        else {}
                    ),
                    **(
                        {"roleid": int(record["rolename"])}
                        if "rolename" in record
                        and record["rolename"] is not None
                        and str(record["rolename"]).isdigit()
                        else (
                            {"rolename": record["rolename"]}
                            if "rolename" in record and record["rolename"] is not None
                            else {}
                        )
                    ),
                    **(
                        {"roleid": int(record["roleid"])}
                        if "roleid" in record and record["roleid"] is not None
                        else {}
                    ),
                }
                for record in records
            ]
        }
        if options:
            if "finaltime" in options:
                data["finaltime"] = options["finaltime"]
            if "slidingtime" in options:
                data["slidingtime"] = options["slidingtime"]
        return self._make_request("UserCreateBulk", data, request_metadata)

    def get_user(
        self,
        mode: str,
        identity: str,
        version: Optional[int] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Get user information from DatabunkerPro."""
        data: Dict[str, Any] = {
            "mode": mode,
            "identity": identity,
        }
        if version is not None:
            data["version"] = version
        return self._make_request("UserGet", data, request_metadata)

    def update_user(
        self,
        mode: str,
        identity: str,
        profile: Dict[str, Any],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Update user information in DatabunkerPro."""
        data = {
            "mode": mode,
            "identity": identity,
            "profile": profile,
        }
        return self._make_request("UserUpdate", data, request_metadata)

    def request_user_update(
        self,
        mode: str,
        identity: str,
        profile: Dict[str, Any],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Request update of user information in DatabunkerPro."""
        data = {
            "mode": mode,
            "identity": identity,
            "profile": profile,
        }
        return self._make_request("UserUpdateRequest", data, request_metadata)

    def patch_user(
        self,
        mode: str,
        identity: str,
        patch: List[PatchOperation],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Patch a user record with specific changes."""
        data = {
            "mode": mode,
            "identity": identity,
            "patch": patch,
        }
        return self._make_request("UserPatch", data, request_metadata)

    def request_user_patch(
        self,
        mode: str,
        identity: str,
        patch: List[PatchOperation],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Request a user patch operation."""
        data = {
            "mode": mode,
            "identity": identity,
            "patch": patch,
        }
        return self._make_request("UserPatchRequest", data, request_metadata)

    def delete_user(
        self,
        mode: str,
        identity: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Delete a user from DatabunkerPro."""
        data = {
            "mode": mode,
            "identity": identity,
        }
        return self._make_request("UserDelete", data, request_metadata)

    def delete_users_bulk(
        self,
        users: List[Dict[str, str]],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """
        Delete multiple users in bulk from DatabunkerPro.

        Args:
            users: List of user dictionaries containing mode and identity for each user to delete
            request_metadata: Optional request metadata

        Returns:
            Dict containing the result of the bulk deletion operation

        Example:
            >>> users_to_delete = [
            ...     {"mode": "email", "identity": "user1@example.com"},
            ...     {"mode": "phone", "identity": "+1234567890"}
            ... ]
            >>> result = api.delete_users_bulk(users_to_delete)
            >>> print(result)
            {'status': 'ok', 'deleted_count': 2}
        """
        data = {"users": users}
        return self._make_request("UserDeleteBulk", data, request_metadata)

    def request_user_deletion(
        self,
        mode: str,
        identity: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Request deletion of a user from DatabunkerPro."""
        data = {
            "mode": mode,
            "identity": identity,
        }
        return self._make_request("UserDeleteRequest", data, request_metadata)

    def search_user(
        self,
        identity: str,
        unlock_uuid: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Search for a user with unlock UUID. Mode is auto-detected from identity."""
        data = {
            "identity": identity,
            "unlockuuid": unlock_uuid,
        }
        return self._make_request("UserSearch", data, request_metadata)

    def list_user_versions(
        self,
        mode: str,
        identity: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List all versions of a user record."""
        data = {
            "mode": mode,
            "identity": identity,
        }
        return self._make_request("UserListVersions", data, request_metadata)

    def create_user_x_token(
        self,
        mode: str,
        identity: str,
        options: Optional[BasicOptions] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Creates an access token for a user."""
        data = {"mode": mode, "identity": identity}
        if options:
            data.update(cast(Dict[str, Any], options))
        return self._make_request("XTokenCreateForUser", data, request_metadata)

    def create_role_x_token(
        self,
        role_ref: Union[str, int],
        options: Optional[BasicOptions] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Creates an access token for a role."""
        data: Dict[str, Any] = {}
        if options:
            data.update(cast(Dict[str, Any], options))
        if isinstance(role_ref, int) or str(role_ref).isdigit():
            data["roleid"] = int(role_ref)
        else:
            data["rolename"] = str(role_ref)
        return self._make_request("XTokenCreateForRole", data, request_metadata)

    # User Request Management
    def get_user_request(
        self, request_uuid: str, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """Get a specific user request by UUID."""
        data = {
            "requestuuid": request_uuid,
        }
        return self._make_request("UserRequestGet", data, request_metadata)

    def list_user_requests(
        self,
        mode: str,
        identity: str,
        offset: int = 0,
        limit: int = 10,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List user requests for a specific user."""
        data = {
            "mode": mode,
            "identity": identity,
            "offset": offset,
            "limit": limit,
        }
        return self._make_request("UserRequestListUserRequests", data, request_metadata)

    def cancel_user_request(
        self,
        request_uuid: str,
        options: Optional[Dict[str, Any]] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Cancels a user request."""
        data = {"requestuuid": request_uuid}
        if options and "reason" in options:
            data["reason"] = options["reason"]
        return self._make_request("UserRequestCancel", data, request_metadata)

    def approve_user_request(
        self,
        request_uuid: str,
        options: Optional[Dict[str, Any]] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Approve a user request."""
        data = {"requestuuid": request_uuid}
        if options and "reason" in options:
            data["reason"] = options["reason"]
        return self._make_request("UserRequestApprove", data, request_metadata)

    # App Data Management
    def create_app_data(
        self,
        mode: str,
        identity: str,
        appname: str,
        appdata: Dict[str, Any],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Create application data for a user."""
        data = {
            "mode": mode,
            "identity": identity,
            "appname": appname,
            "appdata": appdata,
        }
        return self._make_request("AppdataCreate", data, request_metadata)

    def get_app_data(
        self,
        mode: str,
        identity: str,
        appname: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Get application data for a user."""
        data = {
            "mode": mode,
            "identity": identity,
            "appname": appname,
        }
        return self._make_request("AppdataGet", data, request_metadata)

    def update_app_data(
        self,
        mode: str,
        identity: str,
        appname: str,
        appdata: Dict[str, Any],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Update application data for a user."""
        data = {
            "mode": mode,
            "identity": identity,
            "appname": appname,
            "appdata": appdata,
        }
        return self._make_request("AppdataUpdate", data, request_metadata)

    def request_app_data_update(
        self,
        mode: str,
        identity: str,
        appname: str,
        appdata: Dict[str, Any],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Request update of application data for a user."""
        data = {
            "mode": mode,
            "identity": identity,
            "appname": appname,
            "appdata": appdata,
        }
        return self._make_request("AppdataUpdateRequest", data, request_metadata)

    def list_app_data_names(
        self,
        mode: str,
        identity: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List all application data records for a user."""
        data = {
            "mode": mode,
            "identity": identity,
        }
        return self._make_request("AppdataListUserAppNames", data, request_metadata)

    def list_app_names(
        self, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """List all application names in the system."""
        return self._make_request("AppdataListAppNames", None, request_metadata)

    def list_app_data_versions(
        self,
        mode: str,
        identity: str,
        appname: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List all versions of application data for a user."""
        data = {
            "mode": mode,
            "identity": identity,
            "appname": appname,
        }
        return self._make_request("AppdataListVersions", data, request_metadata)

    def delete_app_data(
        self,
        mode: str,
        identity: str,
        appname: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Delete application data for a user."""
        data = {
            "mode": mode,
            "identity": identity,
            "appname": appname,
        }
        return self._make_request("AppdataDelete", data, request_metadata)

    # File Storage
    def create_file(
        self,
        mode: str,
        identity: str,
        filename: str,
        filedata: str,
        options: Optional[FileOptions] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Store an encrypted file for a user.

        Args:
            mode: User identification mode (login, token, email, phone, custom)
            identity: User identifier corresponding to the mode
            filename: Name of the file
            filedata: File content, base64-encoded
            options: Optional mimetype, tags, slidingtime, finaltime
            request_metadata: Additional metadata to include with the request

        Returns:
            The stored file information, including its fileuuid
        """
        data: Dict[str, Any] = {
            "mode": mode,
            "identity": identity,
            "filename": filename,
            "filedata": filedata,
        }
        if options:
            for key in ("mimetype", "tags", "slidingtime", "finaltime"):
                if key in options:
                    data[key] = options[key]
        return self._make_request("FileCreate", data, request_metadata)

    def get_file(
        self,
        mode: str,
        identity: str,
        fileuuid: Optional[str] = None,
        filename: Optional[str] = None,
        raw: Optional[bool] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Get a user file, selected by fileuuid or filename.

        At least one of fileuuid or filename is required. When selecting by
        filename, the most recently created file with that name is returned.
        """
        data: Dict[str, Any] = {
            "mode": mode,
            "identity": identity,
        }
        if fileuuid is not None:
            data["fileuuid"] = fileuuid
        if filename is not None:
            data["filename"] = filename
        if raw is not None:
            data["raw"] = raw
        return self._make_request("FileGet", data, request_metadata)

    def list_user_files(
        self,
        mode: str,
        identity: str,
        tag: Optional[str] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List the metadata of all files owned by a user.

        Args:
            mode: User identification mode (login, token, email, phone, custom)
            identity: User identifier corresponding to the mode
            tag: Optional. Return only files carrying this tag. A single tag
                only — a comma-separated list is not split.
            request_metadata: Additional metadata to include with the request
        """
        data: Dict[str, Any] = {
            "mode": mode,
            "identity": identity,
        }
        if tag is not None:
            data["tag"] = tag
        return self._make_request("FileListUserFiles", data, request_metadata)

    def replace_file_tags(
        self,
        mode: str,
        identity: str,
        fileuuid: str,
        tags: Union[List[str], str],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Replace the complete tag set on a file.

        The supplied list is authoritative — tags not included are removed.
        Tags are lowercased and de-duplicated, must match
        ^[a-z0-9][a-z0-9._-]{0,49}$, and at most 16 are kept.
        """
        data: Dict[str, Any] = {
            "mode": mode,
            "identity": identity,
            "fileuuid": fileuuid,
            "tags": tags,
        }
        return self._make_request("FileReplaceTags", data, request_metadata)

    def delete_file(
        self,
        mode: str,
        identity: str,
        fileuuid: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Delete a user file."""
        data = {
            "mode": mode,
            "identity": identity,
            "fileuuid": fileuuid,
        }
        return self._make_request("FileDelete", data, request_metadata)

    # Legal Basis Management
    def create_legal_basis(
        self,
        options: LegalBasisOptions,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Create a legal basis for data processing."""
        data = _add_options(
            {},
            options,
            (
                "brief",
                "status",
                "module",
                "fulldesc",
                "shortdesc",
                "basistype",
                "requiredmsg",
                "requiredflag",
            ),
        )
        return self._make_request("LegalBasisCreate", data, request_metadata)

    def update_legal_basis(
        self,
        brief: str,
        options: LegalBasisUpdateOptions,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Update an existing legal basis."""
        data: Dict[str, Any] = {"brief": brief}
        if options.get("status") is not None:
            data["status"] = options["status"]
        if options.get("module") is not None:
            data["module"] = options["module"]
        if options.get("fulldesc") is not None:
            data["fulldesc"] = options["fulldesc"]
        if options.get("shortdesc") is not None:
            data["shortdesc"] = options["shortdesc"]
        if options.get("basistype") is not None:
            data["basistype"] = options["basistype"]
        if options.get("requiredmsg") is not None:
            data["requiredmsg"] = options["requiredmsg"]
        if options.get("requiredflag") is not None:
            data["requiredflag"] = options["requiredflag"]
        return self._make_request("LegalBasisUpdate", data, request_metadata)

    def delete_legal_basis(
        self, brief: str, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """Delete a legal basis."""
        data = {"brief": brief}
        return self._make_request("LegalBasisDelete", data, request_metadata)

    def list_agreements(
        self, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """List all agreements."""
        return self._make_request("LegalBasisListAgreements", None, request_metadata)

    # Agreement Management
    def accept_agreement(
        self,
        mode: str,
        identity: str,
        brief: str,
        options: AgreementAcceptOptions,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Accept an agreement for a user."""
        data: Dict[str, Any] = {
            "mode": mode,
            "identity": identity,
            "brief": brief,
        }
        if options.get("agreementmethod"):
            data["agreementmethod"] = options["agreementmethod"]
        if options.get("lastmodifiedby"):
            data["lastmodifiedby"] = options["lastmodifiedby"]
        if options.get("referencecode"):
            data["referencecode"] = options["referencecode"]
        if options.get("starttime"):
            data["starttime"] = options["starttime"]
        if options.get("finaltime"):
            data["finaltime"] = options["finaltime"]
        if options.get("status"):
            data["status"] = options["status"]
        return self._make_request("AgreementAccept", data, request_metadata)

    def get_user_agreement(
        self,
        mode: str,
        identity: str,
        brief: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Get a specific agreement for a user."""
        data: Dict[str, Any] = {
            "mode": mode,
            "identity": identity,
            "brief": brief,
        }
        return self._make_request("AgreementGet", data, request_metadata)

    def list_user_agreements(
        self,
        mode: str,
        identity: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List all agreements for a user."""
        data = {
            "mode": mode,
            "identity": identity,
        }
        return self._make_request("AgreementListUserAgreements", data, request_metadata)

    def cancel_agreement(
        self,
        mode: str,
        identity: str,
        brief: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Cancel an agreement for a user."""
        data = {
            "mode": mode,
            "identity": identity,
            "brief": brief,
        }
        return self._make_request("AgreementCancel", data, request_metadata)

    def request_agreement_cancellation(
        self,
        mode: str,
        identity: str,
        brief: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Request cancellation of an agreement for a user."""
        data = {
            "mode": mode,
            "identity": identity,
            "brief": brief,
        }
        return self._make_request("AgreementCancelRequest", data, request_metadata)

    def revoke_all_agreements(
        self, brief: str, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """Revoke all agreements for a specific legal basis."""
        data = {"brief": brief}
        return self._make_request("AgreementRevokeAll", data, request_metadata)

    # Processing Activity Management
    def list_processing_activities(
        self, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """List all processing activities."""
        return self._make_request(
            "ProcessingActivityListActivities", None, request_metadata
        )

    def create_processing_activity(
        self,
        options: ProcessingActivityOptions,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Create a new processing activity."""
        data = _add_options(
            {}, options, ("activity", "title", "script", "fulldesc", "applicableto")
        )
        return self._make_request("ProcessingActivityCreate", data, request_metadata)

    def update_processing_activity(
        self,
        activity: str,
        options: ProcessingActivityUpdateOptions,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Update an existing processing activity."""
        data: Dict[str, Any] = {"activity": activity}
        if options.get("newactivity") is not None:
            data["newactivity"] = options["newactivity"]
        if options.get("title") is not None:
            data["title"] = options["title"]
        if options.get("script") is not None:
            data["script"] = options["script"]
        if options.get("fulldesc") is not None:
            data["fulldesc"] = options["fulldesc"]
        if options.get("applicableto") is not None:
            data["applicableto"] = options["applicableto"]
        return self._make_request("ProcessingActivityUpdate", data, request_metadata)

    def delete_processing_activity(
        self, activity: str, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """Delete a processing activity."""
        data = {"activity": activity}
        return self._make_request("ProcessingActivityDelete", data, request_metadata)

    def link_processing_activity_to_legal_basis(
        self,
        activity: str,
        brief: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Link a processing activity to a legal basis."""
        data = {
            "activity": activity,
            "brief": brief,
        }
        return self._make_request(
            "ProcessingActivityLinkLegalBasis", data, request_metadata
        )

    def unlink_processing_activity_from_legal_basis(
        self,
        activity: str,
        brief: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Unlink a processing activity from a legal basis."""
        data = {
            "activity": activity,
            "brief": brief,
        }
        return self._make_request(
            "ProcessingActivityUnlinkLegalBasis", data, request_metadata
        )

    # Group Management
    def create_group(
        self,
        options: GroupOptions,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Create a new group."""
        data = _add_options({}, options, ("groupname", "groupdesc", "grouptype"))
        return self._make_request("GroupCreate", data, request_metadata)

    def get_group(
        self,
        group_ref: Union[str, int],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Get group information."""
        data: Dict[str, Any] = {}
        if isinstance(group_ref, int) or str(group_ref).isdigit():
            data["groupid"] = int(group_ref)
        else:
            data["groupname"] = str(group_ref)
        return self._make_request("GroupGet", data, request_metadata)

    def list_all_groups(
        self, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """List all groups in the system."""
        return self._make_request("GroupListAllGroups", None, request_metadata)

    def list_user_groups(
        self,
        mode: str,
        identity: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List groups for a specific user."""
        data = {
            "mode": mode,
            "identity": identity,
        }
        return self._make_request("GroupListUserGroups", data, request_metadata)

    def update_group(
        self,
        group_id: int,
        options: GroupOptions,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Update group information."""
        data = {**options}
        data["groupid"] = int(group_id)
        return self._make_request("GroupUpdate", data, request_metadata)

    def delete_group(
        self,
        group_ref: Union[str, int],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Delete a group."""
        data: Dict[str, Any] = {}
        if isinstance(group_ref, int) or str(group_ref).isdigit():
            data["groupid"] = int(group_ref)
        else:
            data["groupname"] = str(group_ref)
        return self._make_request("GroupDelete", data, request_metadata)

    def remove_user_from_group(
        self,
        mode: str,
        identity: str,
        group_ref: Union[str, int],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Remove a user from a group."""
        data: Dict[str, Any] = {"mode": mode, "identity": identity}
        if isinstance(group_ref, int) or str(group_ref).isdigit():
            data["groupid"] = int(group_ref)
        else:
            data["groupname"] = str(group_ref)
        return self._make_request("GroupDeleteUser", data, request_metadata)

    def add_user_to_group(
        self,
        mode: str,
        identity: str,
        group_ref: Union[str, int],
        role_ref: Optional[Union[str, int]] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Add a user to a group with an optional role."""
        data: Dict[str, Any] = {"mode": mode, "identity": identity}
        if isinstance(group_ref, int) or str(group_ref).isdigit():
            data["groupid"] = int(group_ref)
        else:
            data["groupname"] = str(group_ref)
        if role_ref is not None:
            if isinstance(role_ref, int) or str(role_ref).isdigit():
                data["roleid"] = int(role_ref)
            else:
                data["rolename"] = str(role_ref)
        return self._make_request("GroupAddUser", data, request_metadata)

    # Token Management
    def create_token(
        self,
        token_type: str,
        record: str,
        options: Optional[TokenOptions] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Create a token for sensitive data."""
        data = {"tokentype": token_type, "record": record}
        if options:
            data.update(cast(Dict[str, Any], options))
        return self._make_request("TokenCreate", data, request_metadata)

    def create_tokens_bulk(
        self,
        records: List[Dict[str, Any]],
        options: Optional[TokenOptions] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Create multiple tokens in bulk."""
        data = {"records": records}
        if options:
            data.update(cast(Dict[str, Any], options))
        return self._make_request("TokenCreateBulk", data, request_metadata)

    def get_token(
        self, token: str, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """Get token information from DatabunkerPro."""
        return self._make_request("TokenGet", {"token": token}, request_metadata)

    def delete_token(
        self, token: str, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """Delete a token from DatabunkerPro."""
        return self._make_request("TokenDelete", {"token": token}, request_metadata)

    # Audit Management
    def list_user_audit_events(
        self,
        mode: str,
        identity: str,
        offset: int = 0,
        limit: int = 10,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List audit events for a specific user."""
        data = {
            "mode": mode,
            "identity": identity,
            "offset": offset,
            "limit": limit,
        }
        return self._make_request("AuditListUserEvents", data, request_metadata)

    def get_audit_event(
        self, audit_event_uuid: str, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """Get a specific audit event by UUID."""
        return self._make_request(
            "AuditGetEvent", {"auditeventuuid": audit_event_uuid}, request_metadata
        )

    # Tenant Management
    def create_tenant(
        self, options: TenantOptions, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """Create a new tenant."""
        data = _add_options({}, options, ("tenantname", "tenantorg", "email"))
        return self._make_request("TenantCreate", data, request_metadata)

    def get_tenant(
        self,
        tenant_id: Union[str, int],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Get tenant information."""
        return self._make_request(
            "TenantGet", {"tenantid": tenant_id}, request_metadata
        )

    def update_tenant(
        self,
        tenant_id: Union[str, int],
        options: TenantOptions,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Update tenant information."""
        data: Dict[str, Any] = {"tenantid": tenant_id}
        if options.get("tenantname") is not None:
            data["tenantname"] = options["tenantname"]
        if options.get("tenantorg") is not None:
            data["tenantorg"] = options["tenantorg"]
        if options.get("email") is not None:
            data["email"] = options["email"]
        return self._make_request("TenantUpdate", data, request_metadata)

    def delete_tenant(
        self,
        tenant_id: Union[str, int],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Delete a tenant."""
        data = {"tenantid": tenant_id}
        return self._make_request("TenantDelete", data, request_metadata)

    def list_tenants(
        self,
        offset: int = 0,
        limit: int = 10,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List all tenants with pagination."""
        data = {
            "offset": offset,
            "limit": limit,
        }
        return self._make_request("TenantListTenants", data, request_metadata)

    # Role Management
    def create_role(
        self,
        options: RoleOptions,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Create a new role."""
        data = _add_options({}, options, ("rolename", "roledesc"))
        return self._make_request("RoleCreate", data, request_metadata)

    def update_role(
        self,
        role_id: Union[str, int],
        options: RoleOptions,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Update role information."""
        data = {**options}
        if isinstance(role_id, int) or str(role_id).isdigit():
            data["roleid"] = int(role_id)
        else:
            data["rolename"] = str(role_id)
        return self._make_request("RoleUpdate", data, request_metadata)

    def link_policy(
        self,
        role_ref: Union[str, int],
        policy_ref: Union[str, int],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Link a policy to a role."""
        data: Dict[str, Any] = {}
        if isinstance(role_ref, int) or str(role_ref).isdigit():
            data["roleid"] = int(role_ref)
        else:
            data["rolename"] = str(role_ref)
        if isinstance(policy_ref, int) or str(policy_ref).isdigit():
            data["policyid"] = int(policy_ref)
        else:
            data["policyname"] = str(policy_ref)
        return self._make_request("RoleLinkPolicy", data, request_metadata)

    # Policy Management
    def create_policy(
        self,
        options: PolicyOptions,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Create a new policy."""
        data = _add_options({}, options, ("policyname", "policydesc", "policy"))
        return self._make_request("PolicyCreate", data, request_metadata)

    def update_policy(
        self,
        policy_id: Union[str, int],
        options: PolicyUpdateOptions,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Update policy information."""
        data = {**options}
        if isinstance(policy_id, int) or str(policy_id).isdigit():
            data["policyid"] = int(policy_id)
        else:
            data["policyname"] = str(policy_id)
        return self._make_request("PolicyUpdate", data, request_metadata)

    def get_policy(
        self,
        policy_ref: Union[str, int],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Get policy information."""
        data: Dict[str, Any] = {}
        if isinstance(policy_ref, int) or str(policy_ref).isdigit():
            data["policyid"] = int(policy_ref)
        else:
            data["policyname"] = str(policy_ref)
        return self._make_request("PolicyGet", data, request_metadata)

    def list_policies(
        self, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """List all policies with enhanced information."""
        return self._make_request("PolicyListAllPolicies", None, request_metadata)

    # Bulk Operations
    def bulk_list_unlock(
        self, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """Start a bulk list unlock operation."""
        return self._make_request("BulkListUnlock", None, request_metadata)

    def bulk_list_users(
        self,
        unlock_uuid: str,
        users: List[Dict[str, str]],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List specific users in a bulk operation."""
        data = {
            "unlockuuid": unlock_uuid,
            "users": users,
        }
        return self._make_request("BulkListUsers", data, request_metadata)

    def bulk_list_all_users(
        self,
        unlock_uuid: str,
        offset: int = 0,
        limit: int = 10,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List all users in a bulk operation with pagination."""
        data = {
            "unlockuuid": unlock_uuid,
            "offset": offset,
            "limit": limit,
        }
        return self._make_request("BulkListAllUsers", data, request_metadata)

    def bulk_list_group_users(
        self,
        unlock_uuid: str,
        group_ref: Union[str, int],
        offset: int = 0,
        limit: int = 10,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List users in a group for a bulk operation."""
        data: Dict[str, Any] = {
            "unlockuuid": unlock_uuid,
            "offset": offset,
            "limit": limit,
        }
        if isinstance(group_ref, int) or str(group_ref).isdigit():
            data["groupid"] = int(group_ref)
        else:
            data["groupname"] = str(group_ref)
        return self._make_request("BulkListGroupUsers", data, request_metadata)

    def bulk_list_all_user_requests(
        self,
        unlock_uuid: str,
        offset: int = 0,
        limit: int = 10,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List all user requests in a bulk operation."""
        data = {
            "unlockuuid": unlock_uuid,
            "offset": offset,
            "limit": limit,
        }
        return self._make_request("BulkListAllUserRequests", data, request_metadata)

    def bulk_list_all_audit_events(
        self,
        unlock_uuid: str,
        offset: int = 0,
        limit: int = 10,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List all audit events in a bulk operation."""
        data = {
            "unlockuuid": unlock_uuid,
            "offset": offset,
            "limit": limit,
        }
        return self._make_request("BulkListAllAuditEvents", data, request_metadata)

    def bulk_list_files_by_tag(
        self,
        unlock_uuid: str,
        tag: str,
        offset: int = 0,
        limit: int = 10,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List files carrying a tag, across all users in the tenant.

        Requires the list_users configuration flag. A single tag only.
        """
        data = {
            "unlockuuid": unlock_uuid,
            "tag": tag,
            "offset": offset,
            "limit": limit,
        }
        return self._make_request("BulkListFilesByTag", data, request_metadata)

    def bulk_list_tokens(
        self,
        unlock_uuid: str,
        tokens: List[str],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List tokens in a bulk operation."""
        data = {
            "unlockuuid": unlock_uuid,
            "tokens": tokens,
        }
        return self._make_request("BulkListTokens", data, request_metadata)

    def bulk_delete_tokens(
        self,
        unlock_uuid: str,
        tokens: List[str],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Delete tokens in a bulk operation."""
        data = {
            "unlockuuid": unlock_uuid,
            "tokens": tokens,
        }
        return self._make_request("BulkDeleteTokens", data, request_metadata)

    def get_user_html_report(
        self,
        mode: str,
        identity: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Get HTML report for a user."""
        data = {
            "mode": mode,
            "identity": identity,
        }
        return self._make_request("SystemGetUserHTMLReport", data, request_metadata)

    def get_user_profiles(
        self,
        mode: str,
        identity: str,
        unlock_uuid: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Get user profiles across all tenants. Only accessible by the main tenant admin."""
        data = {
            "mode": mode,
            "identity": identity,
            "unlockuuid": unlock_uuid,
        }
        return self._make_request("SystemGetUserProfiles", data, request_metadata)

    def search_user_profiles(
        self,
        identity: str,
        unlock_uuid: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Fuzzy-search user profiles across all tenants. Only accessible by the main tenant admin."""
        data = {
            "identity": identity,
            "unlockuuid": unlock_uuid,
        }
        return self._make_request("SystemSearchUserProfiles", data, request_metadata)

    def delete_user_profiles(
        self,
        mode: str,
        identity: str,
        unlock_uuid: str,
        tenant_ref: Optional[Union[str, int]] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Delete user profiles across all tenants. Only accessible by the main tenant admin."""
        data: Dict[str, Any] = {
            "mode": mode,
            "identity": identity,
            "unlockuuid": unlock_uuid,
        }
        if tenant_ref is not None:
            if isinstance(tenant_ref, int) or str(tenant_ref).isdigit():
                data["tenantid"] = int(tenant_ref)
            else:
                data["tenantname"] = str(tenant_ref)
        return self._make_request("SystemDeleteUserProfiles", data, request_metadata)

    def restore_user_profile(
        self,
        token: str,
        unlock_uuid: str,
        tenant_ref: Union[str, int],
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Restore a deleted user profile for a specific tenant. Only accessible by the main tenant admin."""
        data: Dict[str, Any] = {
            "token": token,
            "unlockuuid": unlock_uuid,
        }
        if isinstance(tenant_ref, int) or str(tenant_ref).isdigit():
            data["tenantid"] = int(tenant_ref)
        else:
            data["tenantname"] = str(tenant_ref)
        return self._make_request("SystemRestoreUserProfile", data, request_metadata)

    def get_user_report(
        self,
        mode: str,
        identity: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Get report for a user."""
        data = {
            "mode": mode,
            "identity": identity,
        }
        return self._make_request("SystemGetUserReport", data, request_metadata)

    def get_system_stats(
        self, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """Gets system statistics."""
        return self._make_request("SystemGetSystemStats", None, request_metadata)

    def get_system_metrics(
        self, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """Get system metrics in Prometheus format."""
        try:
            response = requests.get(f"{self.base_url}/metrics")
            metrics_text = response.text
            return self.parse_prometheus_metrics(metrics_text)
        except Exception as e:
            return {"status": "error", "message": f"Error getting metrics: {str(e)}"}

    def parse_prometheus_metrics(self, metrics_text: str) -> Dict[str, Any]:
        """Parse Prometheus metrics text into a dictionary."""
        metrics = {}
        lines = metrics_text.split("\n")
        for line in lines:
            if line.startswith("#") or not line.strip():
                continue
            match = re.match(r"^([a-zA-Z0-9_]+)(?:{([^}]+)})?\s+([0-9.]+)$", line)
            if match:
                name, labels, value = match.groups()
                metric_key = f"{name}{{{labels}}}" if labels else name
                metrics[metric_key] = float(value)
        return metrics

    def generate_wrapping_key(
        self,
        key1: str,
        key2: str,
        key3: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """
        Generates a wrapping key from three Shamir's Secret Sharing keys.

        Args:
            key1: First Shamir secret sharing key
            key2: Second Shamir secret sharing key
            key3: Third Shamir secret sharing key
            request_metadata: Optional request metadata

        Returns:
            Dict containing the generated wrapping key

        Example:
            >>> result = api.generate_wrapping_key("key1", "key2", "key3")
            >>> print(result)
            {'status': 'ok', 'wrappingkey': 'generated-wrapping-key-value'}
        """
        data = {"key1": key1, "key2": key2, "key3": key3}
        return self._make_request("SystemGenerateWrappingKey", data, request_metadata)

    def set_license_key(
        self,
        license_key: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """
        Set the license key for the system.

        Args:
            license_key: The license key to set
            request_metadata: Optional request metadata

        Returns:
            Dict containing the result of the license key setting operation

        Example:
            >>> result = api.set_license_key("your-license-key-here")
            >>> print(result)
            {'status': 'ok', 'message': 'License key set successfully'}
        """
        data = {"licensekey": license_key}
        return self._make_request("SystemSetLicenseKey", data, request_metadata)

    # Session Management
    def upsert_session(
        self,
        session_uuid: str,
        session_data: Dict[str, Any],
        options: Optional[BasicOptions] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Create or update a session (upsert operation)."""
        data = {"sessionuuid": session_uuid, "sessiondata": session_data}
        if options:
            data.update(cast(Dict[str, Any], options))
        return self._make_request("SessionUpsert", data, request_metadata)

    def delete_session(
        self, session_uuid: str, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """Delete a session."""
        return self._make_request(
            "SessionDelete", {"sessionuuid": session_uuid}, request_metadata
        )

    def list_user_sessions(
        self,
        mode: str,
        identity: str,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """List sessions for a specific user."""
        data = {
            "mode": mode,
            "identity": identity,
        }
        return self._make_request("SessionListUserSessions", data, request_metadata)

    def get_session(
        self, session_uuid: str, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """Get session information."""
        data = {"sessionuuid": session_uuid}
        return self._make_request("SessionGet", data, request_metadata)

    # Shared Record Management
    def create_shared_record(
        self,
        mode: str,
        identity: str,
        options: Optional[SharedRecordOptions] = None,
        request_metadata: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Creates a shared record for a user."""
        data: Dict[str, Any] = {"mode": mode, "identity": identity}
        _add_options(data, options, ("fields", "partner", "appname", "finaltime"))
        return self._make_request("SharedRecordCreate", data, request_metadata)

    def get_shared_record(
        self, record_uuid: str, request_metadata: Optional[Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """Gets a shared record by its UUID."""
        data = {"recorduuid": record_uuid}
        return self._make_request("SharedRecordGet", data, request_metadata)