Home

Endpoints for managing the home screen functionality. These endpoints provide access to user's personalized content including letters, affirmations, backgrounds, and settings.

Get Home

Returns the user's personalized home screen content. This includes daily letters and affirmations. When detailed mode is enabled, it also returns the user's intention data, background preferences, and additional content like open questions and music selections.

Endpoint

• Method: GET
• URL: /api/home

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
Authorization	Bearer YOUR_API_TOKEN	Yes

Query Parameters

Parameter	Type	Required	Description
is_refreshing	boolean	No	If true, refreshes intention data
detail	boolean	No	If true, returns detailed home data

Success Response

Basic Response

{
    "success": true,
    "message": "Data has been retrieved successfully",
    "data": {
        "letters": [
            {
                "id": 1,
                "name": "Letter name",
                "is_favorite": false,
                "favorite_id": null,
                "liked_by_me_count": 0,
                "is_vip": false,
                "can_access": true
            }
        ],
        "affirmations": [
            {
                "id": 1,
                "text": "Affirmation text",
                "is_vip": false,
                "can_access": true,
                "is_favorite": false,
                "favorite_id": null,
                "liked_by_me_count": 0,
                "read_by_auth_count": 0
            }
        ]
    },
    "status_code": 200
}```

#### Detailed Response (with detail=true)
```json
{
    "success": true,
    "message": "Data has been retrieved successfully",
    "data": {
        "intention": "Career Growth",
        "intention_id": 1,
        "background": {
            "id": 1,
            "name": "Background name",
            "image_url": "https://example.com/background.jpg",
            "width": 1920,
            "height": 1080,
            "color_theme": "light",
            "background_opacity": 0.8
        },
        "letters": [
            {
                "id": 1,
                "name": "Letter name",
                "is_favorite": false,
                "favorite_id": null,
                "liked_by_me_count": 0,
                "is_vip": false,
                "can_access": true
            }
        ],
        "open_questions": [],
        "deconstruction_question": [],
        "intention_musics": [],
        "affirmations": {
            "all_affirmations": [
                {
                    "id": 1,
                    "text": "Affirmation text",
                    "is_vip": false,
                    "can_access": true,
                    "is_favorite": false,
                    "favorite_id": null,
                    "liked_by_me_count": 0,
                    "read_by_auth_count": 0
                }
            ],
            "custom_affirmations": [],
            "audio_affirmations": []
        }
    },
    "status_code": 200
}

Error Responses

Unauthorized (401)

{
    "success": false,
    "message": "Unauthenticated",
    "data": null,
    "status_code": 401
}

No Intention Found (404)

{
    "success": false,
    "message": "No customer intention found",
    "data": [],
    "status_code": 404
}

Implementation Flow

1. Authentication Check

   • Ensure user is authenticated
   • Load user profile

2. Handle Intention Refresh (if is_refreshing=true)

   • Refresh intention data for the user's profile
   • Update relevant intention-based content

3. Basic Data Flow

   • Return today's letters and affirmations (limited to 40)
   • Format response using appropriate resources

4. Detailed Data Flow (if detail=true)

   • Load user profile with intention and music relationships
   • Check VIP subscription for custom affirmations access
   • Get current background based on user settings
   • Collect all user-specific lists:
     • Letters
     • Open probability questions
     • Deconstruction questions
     • Intention musics
     • All affirmations
     • Custom affirmations (if VIP)

5. Error Handling

   • Handle authentication failures
   • Check for missing intention
   • Return appropriate error responses

6. Response Formatting

   • Format all data using appropriate resources
   • Return success response with formatted data`

Get Background

Retrieves the user's current background settings. The background can be either an image or a video, determined by the user's preferences and profile settings. The response includes the background's type and URL.

Endpoint

• Method: GET
• URL: /api/home/background

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
Authorization	Bearer YOUR_API_TOKEN	Yes

Success Response

{
    "success": true,
    "message": "Data has been retrieved successfully",
    "data": {
        "id": 1,
        "name": "Peaceful Mountain",
        "image_url": "https://example.com/backgrounds/peace.jpg",
        "width": 1920,
        "height": 1080,
        "color_theme": "light",
        "background_opacity": 0.8
    },
    "status_code": 200
}

Error Responses

Unauthorized (401)

{
    "success": false,
    "message": "Unauthenticated",
    "data": null,
    "status_code": 401
}

Implementation Flow

1. Authentication Check

   • Ensure user is authenticated
   • Load user profile

2. Get Background

   • Use BackgroundService to get background for user's profile
   • Format response using BackgroundResource

Get Settings

Retrieves the application's cached settings. These settings control various aspects of the application's behavior and user experience. Settings are cached for performance and updated periodically by the system.

Endpoint

• Method: GET
• URL: /api/home/settings

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
Authorization	Bearer YOUR_API_TOKEN	Yes

Success Response

{
    "success": true,
    "message": "Data has been retrieved successfully",
    "data": [
        {
            "type": "string",
            "name": "setting_name",
            "value": "setting_value"
        }
    ],
    "status_code": 200
}

Error Responses

Unauthorized (401)

{
    "success": false,
    "message": "Unauthenticated",
    "data": null,
    "status_code": 401
}

Implementation Flow

1. Authentication Check

   • Ensure user is authenticated

2. Get Settings

   • Retrieve cached settings using SettingService
   • Format response using SettingResource
   • Return formatted settings collection