# This file was auto-generated by Fern from our API Definition.

import datetime as dt
import typing

from .. import core
from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
from ..core.request_options import RequestOptions
from ..types.check_username_response import CheckUsernameResponse
from ..types.device_session_response import DeviceSessionResponse
from ..types.image_upload_response import ImageUploadResponse
from ..types.set_current_organization_response import SetCurrentOrganizationResponse
from ..types.update_profile_response import UpdateProfileResponse
from ..types.update_username_response import UpdateUsernameResponse
from ..types.user_profile_response import UserProfileResponse
from ..types.user_response import UserResponse
from ..types.welcome_details_response import WelcomeDetailsResponse
from .raw_client import AsyncRawUserManagementClient, RawUserManagementClient

# this is used as the default value for optional parameters
OMIT = typing.cast(typing.Any, ...)


class UserManagementClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawUserManagementClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> RawUserManagementClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        RawUserManagementClient
        """
        return self._raw_client

    def list_users(
        self,
        *,
        skip: typing.Optional[int] = None,
        limit: typing.Optional[int] = None,
        active_only: typing.Optional[bool] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> typing.List[UserResponse]:
        """
        List users with pagination.

        **Requires Authentication:** Bearer token in Authorization header

        Args:
            skip: Number of records to skip
            limit: Maximum number of records to return
            active_only: If True, return only active users

        Parameters
        ----------
        skip : typing.Optional[int]

        limit : typing.Optional[int]

        active_only : typing.Optional[bool]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.List[UserResponse]
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.list_users()
        """
        _response = self._raw_client.list_users(
            skip=skip, limit=limit, active_only=active_only, request_options=request_options
        )
        return _response.data

    def create_user(
        self,
        *,
        email: str,
        password: str,
        first_name: typing.Optional[str] = OMIT,
        last_name: typing.Optional[str] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> UserResponse:
        """
        Create a new user.

        Delegates to service layer for business logic validation.

        Parameters
        ----------
        email : str

        password : str
            Password (min 8 characters)

        first_name : typing.Optional[str]

        last_name : typing.Optional[str]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UserResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.create_user(
            email="email",
            password="password",
        )
        """
        _response = self._raw_client.create_user(
            email=email, password=password, first_name=first_name, last_name=last_name, request_options=request_options
        )
        return _response.data

    def get_current_user_profile(
        self, *, request_options: typing.Optional[RequestOptions] = None
    ) -> UserProfileResponse:
        """
        Get current authenticated user's profile.

        Returns detailed profile information for the logged-in user.

        **Requires Authentication:** Bearer token in Authorization header

        **Available at:**
        - GET /v1/user/me
        - GET /v1/user/profile (alias)

        **Returns:**
        - User ID, email, username
        - Full name, first name, last name
        - Profile image, timezone
        - Account status and verification info
        - Timestamps (created_at, updated_at, last_login)

        Parameters
        ----------
        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UserProfileResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.get_current_user_profile()
        """
        _response = self._raw_client.get_current_user_profile(request_options=request_options)
        return _response.data

    def update_user_profile(
        self,
        *,
        username: typing.Optional[str] = OMIT,
        first_name: typing.Optional[str] = OMIT,
        last_name: typing.Optional[str] = OMIT,
        full_name: typing.Optional[str] = OMIT,
        birthday: typing.Optional[dt.date] = OMIT,
        gender: typing.Optional[str] = OMIT,
        profile_image: typing.Optional[str] = OMIT,
        timezone: typing.Optional[str] = OMIT,
        country_id: typing.Optional[str] = OMIT,
        post_code: typing.Optional[str] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> UpdateProfileResponse:
        """
        Update current user's profile.

        Allows partial updates to user profile fields. Only provided fields will be updated.

        **Requires Authentication:** Bearer token in Authorization header

        **Updatable Fields:**
        - username: Must be unique (3-100 characters, lowercase letters/numbers/dots/underscores/hyphens)
        - first_name, last_name, full_name: Personal names
        - birthday: Date of birth (YYYY-MM-DD format, cannot be in future)
        - gender: Gender identity
        - profile_image: Profile image URL
        - timezone: User's timezone
        - country_id: Country ID (must be valid country_ prefixed ID)
        - post_code: Postal/ZIP code

        **Note:** Email cannot be updated through this endpoint.

        **Returns:**
        - success: Whether the update was successful
        - message: Success message
        - profile: Updated user profile with all fields

        **Errors:**
        - 401: Not authenticated
        - 404: User not found
        - 409: Username already taken
        - 422: Validation error (invalid country_id, future birthday, etc.)

        Parameters
        ----------
        username : typing.Optional[str]
            Username

        first_name : typing.Optional[str]
            First name

        last_name : typing.Optional[str]
            Last name

        full_name : typing.Optional[str]
            Full name

        birthday : typing.Optional[dt.date]
            Date of birth

        gender : typing.Optional[str]
            Gender

        profile_image : typing.Optional[str]
            Profile image URL

        timezone : typing.Optional[str]
            Timezone

        country_id : typing.Optional[str]
            Country ID (country_ prefix)

        post_code : typing.Optional[str]
            Postal code

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UpdateProfileResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.update_user_profile()
        """
        _response = self._raw_client.update_user_profile(
            username=username,
            first_name=first_name,
            last_name=last_name,
            full_name=full_name,
            birthday=birthday,
            gender=gender,
            profile_image=profile_image,
            timezone=timezone,
            country_id=country_id,
            post_code=post_code,
            request_options=request_options,
        )
        return _response.data

    def set_current_organization(
        self, *, organization_id: str, request_options: typing.Optional[RequestOptions] = None
    ) -> SetCurrentOrganizationResponse:
        """
        Set current organization for the authenticated user.

        Switches the user's active organization context.

        **Requires Authentication:** Bearer token in Authorization header

        **Request Body:**
        - organization_id: Organization ID (must start with 'org_')

        **Returns:**
        - success: Whether the switch was successful
        - message: Success message
        - current_organization_id: The new current organization ID
        - organization: Basic organization details

        **Errors:**
        - 401: Not authenticated
        - 403: User is not a member of the organization
        - 404: Organization not found
        - 422: Invalid organization ID format

        Parameters
        ----------
        organization_id : str
            Organization ID to set as current (org_xxx format)

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        SetCurrentOrganizationResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.set_current_organization(
            organization_id="organization_id",
        )
        """
        _response = self._raw_client.set_current_organization(
            organization_id=organization_id, request_options=request_options
        )
        return _response.data

    def get_user_by_email(self, email: str, *, request_options: typing.Optional[RequestOptions] = None) -> UserResponse:
        """
        Get a user by email address.

        Parameters
        ----------
        email : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UserResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.get_user_by_email(
            email="email",
        )
        """
        _response = self._raw_client.get_user_by_email(email, request_options=request_options)
        return _response.data

    def update_username(
        self, *, username: str, request_options: typing.Optional[RequestOptions] = None
    ) -> UpdateUsernameResponse:
        """
        Update current user's username.

        **Requirements:**
        - 3-100 characters
        - Lowercase letters, numbers, dots, underscores, hyphens only
        - Must be unique

        **Requires Authentication:** Bearer token in Authorization header

        **Errors:**
        - 401: Not authenticated
        - 404: User not found
        - 409: Username already taken
        - 422: Invalid username format

        Parameters
        ----------
        username : str
            New username (3-100 characters)

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UpdateUsernameResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.update_username(
            username="username",
        )
        """
        _response = self._raw_client.update_username(username=username, request_options=request_options)
        return _response.data

    def check_username_availability(
        self, *, username: str, request_options: typing.Optional[RequestOptions] = None
    ) -> CheckUsernameResponse:
        """
        Check if a username is available.

        Validates username format and checks if it's already taken.
        This endpoint does not require authentication.

        **Returns:**
        - available: Whether username is available
        - username: Normalized username
        - message: Explanation of availability status

        Parameters
        ----------
        username : str
            Username to check

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        CheckUsernameResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.check_username_availability(
            username="username",
        )
        """
        _response = self._raw_client.check_username_availability(username=username, request_options=request_options)
        return _response.data

    def get_user_devices(
        self, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.List[DeviceSessionResponse]:
        """
        Get all active device sessions for current user.

        Returns a list of devices where the user is currently logged in.
        Useful for security/session management features.

        **Requires Authentication:** Bearer token in Authorization header

        **Returns:**
        - List of active device sessions
        - Each device includes: ID, name, platform, OS, location, last used time

        Parameters
        ----------
        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.List[DeviceSessionResponse]
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.get_user_devices()
        """
        _response = self._raw_client.get_user_devices(request_options=request_options)
        return _response.data

    def get_welcome_details(self, *, request_options: typing.Optional[RequestOptions] = None) -> WelcomeDetailsResponse:
        """
        Get welcome details for current user.

        Returns organization information for display on welcome/onboarding screens.
        Prioritizes organizations matching the user's email domain.

        **Requires Authentication:** Bearer token in Authorization header

        **Returns:**
        - name: Organization or user name
        - logo: Organization logo URL (if available)
        - email: Contact email address (organization owner)

        **Priority Logic:**
        1. Returns organization matching user's email domain
        2. If no match, returns first organization in user's list
        3. If no organizations, returns user's own details

        Parameters
        ----------
        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        WelcomeDetailsResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.get_welcome_details()
        """
        _response = self._raw_client.get_welcome_details(request_options=request_options)
        return _response.data

    def get_user(self, *, request_options: typing.Optional[RequestOptions] = None) -> UserResponse:
        """
        Get current authenticated user.

        Returns the User model for the currently authenticated user.

        Parameters
        ----------
        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UserResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.get_user()
        """
        _response = self._raw_client.get_user(request_options=request_options)
        return _response.data

    def serve_profile_image(
        self, file_path: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.Any:
        """
        Serve locally stored profile images (development only).

        Parameters
        ----------
        file_path : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.Any
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.serve_profile_image(
            file_path="file_path",
        )
        """
        _response = self._raw_client.serve_profile_image(file_path, request_options=request_options)
        return _response.data

    def upload_profile_image_file(
        self, *, file: core.File, request_options: typing.Optional[RequestOptions] = None
    ) -> ImageUploadResponse:
        """
        Upload a profile image file.

        Accepts image file upload (multipart/form-data) and processes it into
        multiple sizes (thumbnail, medium, full). All images are converted to
        WebP format for optimal compression.

        **Requires Authentication:** Bearer token in Authorization header

        **Supported Formats:**
        - JPEG/JPG
        - PNG
        - WebP
        - GIF

        **Limits:**
        - Maximum file size: 10MB
        - Images are automatically resized to:
          - Thumbnail: 150x150px
          - Medium: 500x500px
          - Full: 1200x1200px

        **Returns:**
        - success: Whether the upload was successful
        - message: Success message
        - urls: Object with thumbnail, medium, and full size image URLs

        **Automatically Updates:** The user's profile_image field is updated
        with the full-size image URL.

        **Errors:**
        - 401: Not authenticated
        - 422: Invalid file type, file too large, or corrupted image

        Parameters
        ----------
        file : core.File
            See core.File for more documentation

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        ImageUploadResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.upload_profile_image_file()
        """
        _response = self._raw_client.upload_profile_image_file(file=file, request_options=request_options)
        return _response.data

    def upload_profile_image_url(
        self, *, image_url: str, request_options: typing.Optional[RequestOptions] = None
    ) -> ImageUploadResponse:
        """
        Upload a profile image from URL.

        Downloads an image from the provided URL and processes it into
        multiple sizes (thumbnail, medium, full). All images are converted to
        WebP format for optimal compression.

        **Requires Authentication:** Bearer token in Authorization header

        **Request Body:**
        ```json
        {
          "image_url": "https://example.com/avatar.jpg"
        }
        ```

        **Supported Formats:**
        - JPEG/JPG
        - PNG
        - WebP
        - GIF

        **Limits:**
        - Maximum file size: 10MB
        - Images are automatically resized to:
          - Thumbnail: 150x150px
          - Medium: 500x500px
          - Full: 1200x1200px

        **Returns:**
        - success: Whether the upload was successful
        - message: Success message
        - urls: Object with thumbnail, medium, and full size image URLs

        **Automatically Updates:** The user's profile_image field is updated
        with the full-size image URL.

        **Errors:**
        - 401: Not authenticated
        - 422: Invalid URL, download failed, invalid file type, or corrupted image

        Parameters
        ----------
        image_url : str
            URL of the image to upload

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        ImageUploadResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.upload_profile_image_url(
            image_url="image_url",
        )
        """
        _response = self._raw_client.upload_profile_image_url(image_url=image_url, request_options=request_options)
        return _response.data

    def get_user_by_id(
        self, user_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> UserProfileResponse:
        """
        Get user profile by ID.

        Returns detailed user profile for the specified user ID.
        Useful for resolving user IDs to names and profile images.

        **Requires Authentication:** Bearer token or API key

        **Path Parameters:**
        - user_id: User ID (must start with 'usr_')

        **Returns:**
        - User ID, email, username
        - Full name, first name, last name
        - Profile image URL
        - Account status (is_active)
        - Timestamps (created_at, updated_at)

        **Errors:**
        - 401: Not authenticated
        - 404: User not found
        - 422: Invalid user ID format

        Parameters
        ----------
        user_id : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UserProfileResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.get_user_by_id(
            user_id="user_id",
        )
        """
        _response = self._raw_client.get_user_by_id(user_id, request_options=request_options)
        return _response.data

    def delete_user(
        self, user_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.Dict[str, typing.Any]:
        """
        Soft delete a user.

        Sets is_deleted and is_active flags. User will no longer appear in
        active user lists but data is preserved.

        **Requires Authentication:** Bearer token in Authorization header

        **Access Control:** Users can only delete their own account.

        **Returns:**
        - success: Whether deletion was successful
        - message: Success message
        - user_id: ID of deleted user

        **Errors:**
        - 401: Not authenticated
        - 403: Attempting to delete another user's account
        - 404: User not found

        Parameters
        ----------
        user_id : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.Dict[str, typing.Any]
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.delete_user(
            user_id="user_id",
        )
        """
        _response = self._raw_client.delete_user(user_id, request_options=request_options)
        return _response.data

    def list_deleted_users(
        self,
        *,
        skip: typing.Optional[int] = None,
        limit: typing.Optional[int] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> typing.List[UserResponse]:
        """
        List deleted users.

        Returns users where is_deleted=True.

        **Requires Authentication:** Bearer token in Authorization header

        **Access Control:** Admin-only endpoint. Requires Owner or Admin role
        in at least one organization.

        **Query Parameters:**
        - skip: Number of records to skip (default: 0)
        - limit: Maximum records to return (default: 100)

        **Returns:**
        List of deleted user profiles with basic information.

        **Errors:**
        - 401: Not authenticated
        - 403: Not an admin user

        Parameters
        ----------
        skip : typing.Optional[int]

        limit : typing.Optional[int]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.List[UserResponse]
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.list_deleted_users()
        """
        _response = self._raw_client.list_deleted_users(skip=skip, limit=limit, request_options=request_options)
        return _response.data

    def get_users_batch(
        self, *, request: typing.Dict[str, typing.Any], request_options: typing.Optional[RequestOptions] = None
    ) -> typing.Dict[str, typing.Any]:
        """
        Get users by specific user IDs (batch lookup).

        **Requires Authentication:** Bearer token in Authorization header

        Args:
            request: Dictionary with 'user_ids' list
            auth: Authenticated user context
            db: Database session
            user_repo: User repository

        Returns:
            Dictionary with users list, total count, and requested IDs

        Parameters
        ----------
        request : typing.Dict[str, typing.Any]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.Dict[str, typing.Any]
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.user_management.get_users_batch(
            request={"key": "value"},
        )
        """
        _response = self._raw_client.get_users_batch(request=request, request_options=request_options)
        return _response.data


class AsyncUserManagementClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawUserManagementClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> AsyncRawUserManagementClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        AsyncRawUserManagementClient
        """
        return self._raw_client

    async def list_users(
        self,
        *,
        skip: typing.Optional[int] = None,
        limit: typing.Optional[int] = None,
        active_only: typing.Optional[bool] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> typing.List[UserResponse]:
        """
        List users with pagination.

        **Requires Authentication:** Bearer token in Authorization header

        Args:
            skip: Number of records to skip
            limit: Maximum number of records to return
            active_only: If True, return only active users

        Parameters
        ----------
        skip : typing.Optional[int]

        limit : typing.Optional[int]

        active_only : typing.Optional[bool]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.List[UserResponse]
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.list_users()


        asyncio.run(main())
        """
        _response = await self._raw_client.list_users(
            skip=skip, limit=limit, active_only=active_only, request_options=request_options
        )
        return _response.data

    async def create_user(
        self,
        *,
        email: str,
        password: str,
        first_name: typing.Optional[str] = OMIT,
        last_name: typing.Optional[str] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> UserResponse:
        """
        Create a new user.

        Delegates to service layer for business logic validation.

        Parameters
        ----------
        email : str

        password : str
            Password (min 8 characters)

        first_name : typing.Optional[str]

        last_name : typing.Optional[str]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UserResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.create_user(
                email="email",
                password="password",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.create_user(
            email=email, password=password, first_name=first_name, last_name=last_name, request_options=request_options
        )
        return _response.data

    async def get_current_user_profile(
        self, *, request_options: typing.Optional[RequestOptions] = None
    ) -> UserProfileResponse:
        """
        Get current authenticated user's profile.

        Returns detailed profile information for the logged-in user.

        **Requires Authentication:** Bearer token in Authorization header

        **Available at:**
        - GET /v1/user/me
        - GET /v1/user/profile (alias)

        **Returns:**
        - User ID, email, username
        - Full name, first name, last name
        - Profile image, timezone
        - Account status and verification info
        - Timestamps (created_at, updated_at, last_login)

        Parameters
        ----------
        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UserProfileResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.get_current_user_profile()


        asyncio.run(main())
        """
        _response = await self._raw_client.get_current_user_profile(request_options=request_options)
        return _response.data

    async def update_user_profile(
        self,
        *,
        username: typing.Optional[str] = OMIT,
        first_name: typing.Optional[str] = OMIT,
        last_name: typing.Optional[str] = OMIT,
        full_name: typing.Optional[str] = OMIT,
        birthday: typing.Optional[dt.date] = OMIT,
        gender: typing.Optional[str] = OMIT,
        profile_image: typing.Optional[str] = OMIT,
        timezone: typing.Optional[str] = OMIT,
        country_id: typing.Optional[str] = OMIT,
        post_code: typing.Optional[str] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> UpdateProfileResponse:
        """
        Update current user's profile.

        Allows partial updates to user profile fields. Only provided fields will be updated.

        **Requires Authentication:** Bearer token in Authorization header

        **Updatable Fields:**
        - username: Must be unique (3-100 characters, lowercase letters/numbers/dots/underscores/hyphens)
        - first_name, last_name, full_name: Personal names
        - birthday: Date of birth (YYYY-MM-DD format, cannot be in future)
        - gender: Gender identity
        - profile_image: Profile image URL
        - timezone: User's timezone
        - country_id: Country ID (must be valid country_ prefixed ID)
        - post_code: Postal/ZIP code

        **Note:** Email cannot be updated through this endpoint.

        **Returns:**
        - success: Whether the update was successful
        - message: Success message
        - profile: Updated user profile with all fields

        **Errors:**
        - 401: Not authenticated
        - 404: User not found
        - 409: Username already taken
        - 422: Validation error (invalid country_id, future birthday, etc.)

        Parameters
        ----------
        username : typing.Optional[str]
            Username

        first_name : typing.Optional[str]
            First name

        last_name : typing.Optional[str]
            Last name

        full_name : typing.Optional[str]
            Full name

        birthday : typing.Optional[dt.date]
            Date of birth

        gender : typing.Optional[str]
            Gender

        profile_image : typing.Optional[str]
            Profile image URL

        timezone : typing.Optional[str]
            Timezone

        country_id : typing.Optional[str]
            Country ID (country_ prefix)

        post_code : typing.Optional[str]
            Postal code

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UpdateProfileResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.update_user_profile()


        asyncio.run(main())
        """
        _response = await self._raw_client.update_user_profile(
            username=username,
            first_name=first_name,
            last_name=last_name,
            full_name=full_name,
            birthday=birthday,
            gender=gender,
            profile_image=profile_image,
            timezone=timezone,
            country_id=country_id,
            post_code=post_code,
            request_options=request_options,
        )
        return _response.data

    async def set_current_organization(
        self, *, organization_id: str, request_options: typing.Optional[RequestOptions] = None
    ) -> SetCurrentOrganizationResponse:
        """
        Set current organization for the authenticated user.

        Switches the user's active organization context.

        **Requires Authentication:** Bearer token in Authorization header

        **Request Body:**
        - organization_id: Organization ID (must start with 'org_')

        **Returns:**
        - success: Whether the switch was successful
        - message: Success message
        - current_organization_id: The new current organization ID
        - organization: Basic organization details

        **Errors:**
        - 401: Not authenticated
        - 403: User is not a member of the organization
        - 404: Organization not found
        - 422: Invalid organization ID format

        Parameters
        ----------
        organization_id : str
            Organization ID to set as current (org_xxx format)

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        SetCurrentOrganizationResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.set_current_organization(
                organization_id="organization_id",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.set_current_organization(
            organization_id=organization_id, request_options=request_options
        )
        return _response.data

    async def get_user_by_email(
        self, email: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> UserResponse:
        """
        Get a user by email address.

        Parameters
        ----------
        email : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UserResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.get_user_by_email(
                email="email",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get_user_by_email(email, request_options=request_options)
        return _response.data

    async def update_username(
        self, *, username: str, request_options: typing.Optional[RequestOptions] = None
    ) -> UpdateUsernameResponse:
        """
        Update current user's username.

        **Requirements:**
        - 3-100 characters
        - Lowercase letters, numbers, dots, underscores, hyphens only
        - Must be unique

        **Requires Authentication:** Bearer token in Authorization header

        **Errors:**
        - 401: Not authenticated
        - 404: User not found
        - 409: Username already taken
        - 422: Invalid username format

        Parameters
        ----------
        username : str
            New username (3-100 characters)

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UpdateUsernameResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.update_username(
                username="username",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.update_username(username=username, request_options=request_options)
        return _response.data

    async def check_username_availability(
        self, *, username: str, request_options: typing.Optional[RequestOptions] = None
    ) -> CheckUsernameResponse:
        """
        Check if a username is available.

        Validates username format and checks if it's already taken.
        This endpoint does not require authentication.

        **Returns:**
        - available: Whether username is available
        - username: Normalized username
        - message: Explanation of availability status

        Parameters
        ----------
        username : str
            Username to check

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        CheckUsernameResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.check_username_availability(
                username="username",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.check_username_availability(
            username=username, request_options=request_options
        )
        return _response.data

    async def get_user_devices(
        self, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.List[DeviceSessionResponse]:
        """
        Get all active device sessions for current user.

        Returns a list of devices where the user is currently logged in.
        Useful for security/session management features.

        **Requires Authentication:** Bearer token in Authorization header

        **Returns:**
        - List of active device sessions
        - Each device includes: ID, name, platform, OS, location, last used time

        Parameters
        ----------
        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.List[DeviceSessionResponse]
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.get_user_devices()


        asyncio.run(main())
        """
        _response = await self._raw_client.get_user_devices(request_options=request_options)
        return _response.data

    async def get_welcome_details(
        self, *, request_options: typing.Optional[RequestOptions] = None
    ) -> WelcomeDetailsResponse:
        """
        Get welcome details for current user.

        Returns organization information for display on welcome/onboarding screens.
        Prioritizes organizations matching the user's email domain.

        **Requires Authentication:** Bearer token in Authorization header

        **Returns:**
        - name: Organization or user name
        - logo: Organization logo URL (if available)
        - email: Contact email address (organization owner)

        **Priority Logic:**
        1. Returns organization matching user's email domain
        2. If no match, returns first organization in user's list
        3. If no organizations, returns user's own details

        Parameters
        ----------
        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        WelcomeDetailsResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.get_welcome_details()


        asyncio.run(main())
        """
        _response = await self._raw_client.get_welcome_details(request_options=request_options)
        return _response.data

    async def get_user(self, *, request_options: typing.Optional[RequestOptions] = None) -> UserResponse:
        """
        Get current authenticated user.

        Returns the User model for the currently authenticated user.

        Parameters
        ----------
        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UserResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.get_user()


        asyncio.run(main())
        """
        _response = await self._raw_client.get_user(request_options=request_options)
        return _response.data

    async def serve_profile_image(
        self, file_path: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.Any:
        """
        Serve locally stored profile images (development only).

        Parameters
        ----------
        file_path : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.Any
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.serve_profile_image(
                file_path="file_path",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.serve_profile_image(file_path, request_options=request_options)
        return _response.data

    async def upload_profile_image_file(
        self, *, file: core.File, request_options: typing.Optional[RequestOptions] = None
    ) -> ImageUploadResponse:
        """
        Upload a profile image file.

        Accepts image file upload (multipart/form-data) and processes it into
        multiple sizes (thumbnail, medium, full). All images are converted to
        WebP format for optimal compression.

        **Requires Authentication:** Bearer token in Authorization header

        **Supported Formats:**
        - JPEG/JPG
        - PNG
        - WebP
        - GIF

        **Limits:**
        - Maximum file size: 10MB
        - Images are automatically resized to:
          - Thumbnail: 150x150px
          - Medium: 500x500px
          - Full: 1200x1200px

        **Returns:**
        - success: Whether the upload was successful
        - message: Success message
        - urls: Object with thumbnail, medium, and full size image URLs

        **Automatically Updates:** The user's profile_image field is updated
        with the full-size image URL.

        **Errors:**
        - 401: Not authenticated
        - 422: Invalid file type, file too large, or corrupted image

        Parameters
        ----------
        file : core.File
            See core.File for more documentation

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        ImageUploadResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.upload_profile_image_file()


        asyncio.run(main())
        """
        _response = await self._raw_client.upload_profile_image_file(file=file, request_options=request_options)
        return _response.data

    async def upload_profile_image_url(
        self, *, image_url: str, request_options: typing.Optional[RequestOptions] = None
    ) -> ImageUploadResponse:
        """
        Upload a profile image from URL.

        Downloads an image from the provided URL and processes it into
        multiple sizes (thumbnail, medium, full). All images are converted to
        WebP format for optimal compression.

        **Requires Authentication:** Bearer token in Authorization header

        **Request Body:**
        ```json
        {
          "image_url": "https://example.com/avatar.jpg"
        }
        ```

        **Supported Formats:**
        - JPEG/JPG
        - PNG
        - WebP
        - GIF

        **Limits:**
        - Maximum file size: 10MB
        - Images are automatically resized to:
          - Thumbnail: 150x150px
          - Medium: 500x500px
          - Full: 1200x1200px

        **Returns:**
        - success: Whether the upload was successful
        - message: Success message
        - urls: Object with thumbnail, medium, and full size image URLs

        **Automatically Updates:** The user's profile_image field is updated
        with the full-size image URL.

        **Errors:**
        - 401: Not authenticated
        - 422: Invalid URL, download failed, invalid file type, or corrupted image

        Parameters
        ----------
        image_url : str
            URL of the image to upload

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        ImageUploadResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.upload_profile_image_url(
                image_url="image_url",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.upload_profile_image_url(
            image_url=image_url, request_options=request_options
        )
        return _response.data

    async def get_user_by_id(
        self, user_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> UserProfileResponse:
        """
        Get user profile by ID.

        Returns detailed user profile for the specified user ID.
        Useful for resolving user IDs to names and profile images.

        **Requires Authentication:** Bearer token or API key

        **Path Parameters:**
        - user_id: User ID (must start with 'usr_')

        **Returns:**
        - User ID, email, username
        - Full name, first name, last name
        - Profile image URL
        - Account status (is_active)
        - Timestamps (created_at, updated_at)

        **Errors:**
        - 401: Not authenticated
        - 404: User not found
        - 422: Invalid user ID format

        Parameters
        ----------
        user_id : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UserProfileResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.get_user_by_id(
                user_id="user_id",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get_user_by_id(user_id, request_options=request_options)
        return _response.data

    async def delete_user(
        self, user_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.Dict[str, typing.Any]:
        """
        Soft delete a user.

        Sets is_deleted and is_active flags. User will no longer appear in
        active user lists but data is preserved.

        **Requires Authentication:** Bearer token in Authorization header

        **Access Control:** Users can only delete their own account.

        **Returns:**
        - success: Whether deletion was successful
        - message: Success message
        - user_id: ID of deleted user

        **Errors:**
        - 401: Not authenticated
        - 403: Attempting to delete another user's account
        - 404: User not found

        Parameters
        ----------
        user_id : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.Dict[str, typing.Any]
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.delete_user(
                user_id="user_id",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.delete_user(user_id, request_options=request_options)
        return _response.data

    async def list_deleted_users(
        self,
        *,
        skip: typing.Optional[int] = None,
        limit: typing.Optional[int] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> typing.List[UserResponse]:
        """
        List deleted users.

        Returns users where is_deleted=True.

        **Requires Authentication:** Bearer token in Authorization header

        **Access Control:** Admin-only endpoint. Requires Owner or Admin role
        in at least one organization.

        **Query Parameters:**
        - skip: Number of records to skip (default: 0)
        - limit: Maximum records to return (default: 100)

        **Returns:**
        List of deleted user profiles with basic information.

        **Errors:**
        - 401: Not authenticated
        - 403: Not an admin user

        Parameters
        ----------
        skip : typing.Optional[int]

        limit : typing.Optional[int]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.List[UserResponse]
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.list_deleted_users()


        asyncio.run(main())
        """
        _response = await self._raw_client.list_deleted_users(skip=skip, limit=limit, request_options=request_options)
        return _response.data

    async def get_users_batch(
        self, *, request: typing.Dict[str, typing.Any], request_options: typing.Optional[RequestOptions] = None
    ) -> typing.Dict[str, typing.Any]:
        """
        Get users by specific user IDs (batch lookup).

        **Requires Authentication:** Bearer token in Authorization header

        Args:
            request: Dictionary with 'user_ids' list
            auth: Authenticated user context
            db: Database session
            user_repo: User repository

        Returns:
            Dictionary with users list, total count, and requested IDs

        Parameters
        ----------
        request : typing.Dict[str, typing.Any]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.Dict[str, typing.Any]
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.user_management.get_users_batch(
                request={"key": "value"},
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get_users_batch(request=request, request_options=request_options)
        return _response.data
