Users API
=========

The Users API provides endpoints for user management, authentication, preferences, and notifications.

App Endpoints
-------------

Get Preferences
~~~~~~~~~~~~~~~

Retrieve user preferences and settings.

.. http:post:: /api/get/preferences/

   **Response:**

   .. code-block:: json

      {
        "user_id": 123,
        "preferences": {
          "language": "en",
          "notifications": {
            "new_campaign": true,
            "end_campaign": true,
            "near_campaign": true,
            "cause_campaign": true,
            "profile_status": true,
            "post_status": true,
            "update_balance": true
          },
          "categories": ["fashion", "beauty", "technology"],
          "networks": ["instagram", "facebook"]
        }
      }

Get Notifications
~~~~~~~~~~~~~~~~~

Retrieve user notifications.

.. http:post:: /api/get/notifications/

   **Response:**

   .. code-block:: json

      {
        "user_id": 123,
        "user_notifications": [
          {
            "name": "New campaign",
            "code": "new_campaign",
            "status": true
          },
          {
            "name": "End campaign",
            "code": "end_campaign",
            "status": true
          },
          {
            "name": "Near campaign",
            "code": "near_campaign",
            "status": false
          },
          {
            "name": "Causes",
            "code": "cause_campaign",
            "status": true
          },
          {
            "name": "Profile status",
            "code": "profile_status",
            "status": true
          },
          {
            "name": "Post status",
            "code": "post_status",
            "status": true
          },
          {
            "name": "Update balance",
            "code": "update_balance",
            "status": true
          }
        ],
        "not_found_message": "No notifications to display"
      }

Get Notifications History
~~~~~~~~~~~~~~~~~~~~~~~~~

Retrieve notification history.

.. http:post:: /api/get/notifications/history/

   **Request Body:**

   .. code-block:: text

      page=1
      limit=20

   **Response:**

   .. code-block:: json

      {
        "notifications": [
          {
            "id": 456,
            "title": "New Campaign Available",
            "message": "A new fashion campaign is available",
            "type": "campaign",
            "read": false,
            "created_at": "2024-08-01T10:00:00Z"
          }
        ],
        "total": 50,
        "page": 1,
        "limit": 20
      }

Authentication Checks
~~~~~~~~~~~~~~~~~~~~~

Check Authentication
^^^^^^^^^^^^^^^^^^^

Check if user is authenticated.

.. http:post:: /api/check/auth/

   **Response:**

   .. code-block:: json

      {
        "is_authenticated": true,
        "user_id": 123,
        "username": "user123"
      }

Check Login
^^^^^^^^^^^

Check login status.

.. http:post:: /api/check/validate/

   **Response:**

   .. code-block:: json

      {
        "is_logged": true,
        "user_id": 123
      }

Check Email
^^^^^^^^^^^

Check if email exists.

.. http:post:: /api/check/email/

   **Request Body:**

   .. code-block:: text

      email=user@example.com

   **Response:**

   .. code-block:: json

      {
        "exists": true,
        "available": false
      }

Update Operations
~~~~~~~~~~~~~~~~~

Update Language
^^^^^^^^^^^^^^

Update user language preference.

.. http:post:: /api/update/language/

   **Request Body:**

   .. code-block:: text

      language=es

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Language updated successfully"
      }

Update Profile
^^^^^^^^^^^^^

Update user profile information.

.. http:post:: /api/update/profile/

   **Request Body:**

   .. code-block:: text

      first_name=John
      last_name=Doe
      email=john.doe@example.com
      phone=+1234567890
      country=1
      city=1

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Profile updated successfully"
      }

Update Preferences
^^^^^^^^^^^^^^^^^

Update user preferences.

.. http:post:: /api/update/preferences/

   **Request Body:**

   .. code-block:: text

      categories=fashion
      categories=beauty
      networks=instagram
      networks=facebook
      language=en

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Preferences updated successfully"
      }

Update Notifications
^^^^^^^^^^^^^^^^^^^^

Update notification settings.

.. http:post:: /api/update/notifications/

   **Request Body:**

   .. code-block:: text

      new_campaign=true
      end_campaign=false
      near_campaign=true
      cause_campaign=true
      profile_status=true
      post_status=true
      update_balance=true

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Notification settings updated"
      }

User Actions
~~~~~~~~~~~~

Register
^^^^^^^^

Register a new user account.

.. http:post:: /api/action/register/

   **Request Body:**

   .. code-block:: text

      username=newuser
      email=newuser@example.com
      password=securepassword
      first_name=John
      last_name=Doe
      country=1
      city=1

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Account created successfully",
        "user_id": 789
      }

Logout
^^^^^^

Logout user and invalidate session.

.. http:post:: /api/action/logout/

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Logged out successfully"
      }

Backend Endpoints
-----------------

Authentication Checks
~~~~~~~~~~~~~~~~~~~~~

Check Login (Backend)
^^^^^^^^^^^^^^^^^^^^

Check login status for backend operations.

.. http:post:: /api/check/login/

   **Response:**

   .. code-block:: json

      {
        "is_logged": true,
        "user_id": 123,
        "is_staff": false,
        "is_superuser": false
      }

Check Validate (Backend)
^^^^^^^^^^^^^^^^^^^^^^^

Validate user credentials for backend operations.

.. http:post:: /api/check/validate/

   **Request Body:**

   .. code-block:: text

      username=user123&password=password123

   **Response:**

   .. code-block:: json

      {
        "is_valid": true,
        "user_id": 123
      }

Check Email (Backend)
^^^^^^^^^^^^^^^^^^^^

Check email existence for backend operations.

.. http:post:: /api/check/email/

   **Request Body:**

   .. code-block:: json

      {
        "email": "user@example.com"
      }

   **Response:**

   .. code-block:: json

      {
        "exists": true,
        "user_id": 123
      }

User Management
~~~~~~~~~~~~~~~

User Statistics
^^^^^^^^^^^^^^

Get user statistics by sex.

.. http:post:: /api/users/stats/sex/

   **Response:**

   .. code-block:: json

      {
        "male": 60,
        "female": 40,
        "other": 0
      }

Get user statistics by age.

.. http:post:: /api/users/stats/age/

   **Response:**

   .. code-block:: json

      {
        "18-24": 30,
        "25-34": 40,
        "35-44": 20,
        "45+": 10
      }

Get user statistics by preferences.

.. http:post:: /api/users/stats/preferences/

   **Response:**

   .. code-block:: json

      {
        "fashion": 25,
        "beauty": 20,
        "technology": 15,
        "food": 10,
        "travel": 10,
        "other": 20
      }

User Status Management
^^^^^^^^^^^^^^^^^^^^^

Ban user.

.. http:post:: /api/user/status/ban/

   **Request Body:**

   .. code-block:: text

      user_id=123
      banned=true
      reason=Violation of terms of service

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "User ban status updated"
      }

Get user status.

.. http:post:: /api/user/status/

   **Request Body:**

   .. code-block:: text

      user_id=123

   **Response:**

   .. code-block:: json

      {
        "status": "active",
        "joined_date": "2024-01-01",
        "last_login": "2024-08-01T10:00:00Z",
        "total_campaigns": 10,
        "total_earnings": 500
      }

User Notifications
^^^^^^^^^^^^^^^^^

Send notification to user.

.. http:post:: /api/user/notification/

   **Request Body:**

   .. code-block:: text

      user_id=123
      title=New Campaign
      message=A new campaign is available for you
      type=campaign

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Notification sent successfully"
      }

Force Logout
^^^^^^^^^^^

Force logout user from all sessions.

.. http:post:: /api/user/force-logout/

   **Request Body:**

   .. code-block:: text

      user_id=123

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "User logged out from all sessions"
      }

Custom Social Wall
^^^^^^^^^^^^^^^^^

Add custom social wall for user.

.. http:post:: /api/user/add-custom-social-wall/

   **Request Body:**

   .. code-block:: text

      user_id=123
      wall_url=https://example.com/social-wall
      network=instagram
      description=Custom social wall for user

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Custom social wall added successfully"
      }

Data Models
-----------

User Profile
~~~~~~~~~~~~

.. code-block:: json

   {
     "id": 123,
     "username": "user123",
     "email": "user@example.com",
     "first_name": "John",
     "last_name": "Doe",
     "date_joined": "2024-01-01T00:00:00Z",
     "last_login": "2024-08-01T10:00:00Z",
     "is_active": true,
     "is_staff": false,
     "is_superuser": false,
     "country": {
       "id": 1,
       "name": "United States"
     },
     "city": {
       "id": 1,
       "name": "New York"
     },
     "language": "en",
     "timezone": "UTC"
   }

User Preferences
~~~~~~~~~~~~~~~

.. code-block:: json

   {
     "user_id": 123,
     "language": "en",
     "notifications": {
       "new_campaign": true,
       "end_campaign": true,
       "near_campaign": true,
       "cause_campaign": true,
       "profile_status": true,
       "post_status": true,
       "update_balance": true
     },
     "categories": ["fashion", "beauty", "technology"],
     "networks": ["instagram", "facebook"],
     "privacy_settings": {
       "profile_public": true,
       "show_earnings": false,
       "show_campaigns": true
     }
   }

Notification
~~~~~~~~~~~~

.. code-block:: json

   {
     "id": 456,
     "user_id": 123,
     "title": "New Campaign Available",
     "message": "A new fashion campaign is available for you",
     "type": "campaign",
     "read": false,
     "created_at": "2024-08-01T10:00:00Z",
     "data": {
       "campaign_id": 789,
       "campaign_name": "Summer Fashion Campaign"
     }
   }

Error Responses
--------------

Authentication Errors
~~~~~~~~~~~~~~~~~~~~

.. code-block:: json

   {
     "error": "authentication_required",
     "message": "Authentication is required for this endpoint"
   }

.. code-block:: json

   {
     "error": "invalid_credentials",
     "message": "Invalid username or password"
   }

Validation Errors
~~~~~~~~~~~~~~~~

.. code-block:: json

   {
     "error": "validation_error",
     "message": "Invalid email format",
     "field": "email"
   }

.. code-block:: json

   {
     "error": "validation_error",
     "message": "Password must be at least 8 characters long",
     "field": "password"
   }

Permission Errors
~~~~~~~~~~~~~~~~

.. code-block:: json

   {
     "error": "permission_denied",
     "message": "You don't have permission to perform this action"
   }

.. code-block:: json

   {
     "error": "user_not_found",
     "message": "User not found"
   }