CloudOperations
Postman Doc: https://documenter.getpostman.com/view/20499442/[merchant-collection-id]

--------------------------------------------------------------------------------
API: Upload Temp File
--------------------------------------------------------------------------------
    POST /merchant/api/v1/files [Util Service / Orchestration]

    Description: Upload a temporary file (multipart/form-data) and receive a temporary ID and preview URL. Used by UIs before committing to domain media.

    Request (multipart/form-data): file=@image.jpg

    Response: 201 Created
        {
            "file_name": "tpwz51gYRxqSi6kwR7Qqtw.png",
            "file_size": 91804,
            "path": "/tmp/tpwz51gYRxqSi6kwR7Qqtw.png",
            "file_extension": ".png",
            "mime_type": "application/image",
            "created_at": "2025-02-20T14:00:00Z",
            "checksum": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
            "storage_type": "tmp",
            "readable": true,
            "writable": false,
            "preview_url": "https://cdn.unizap.ai/tmp/tpwz51gYRxqSi6kwR7Qqtw.png",
            "upload_url": "/tmp/tpwz51gYRxqSi6kwR7Qqtw.png?file_name=logo.png&alt_name=logo.png"
        }
    Flow Sequence:
        # Step 1: Receive multipart upload and validate file
        # Step 2: Store object in temporary bucket (GCS/S3)
        POST /api/cloud/storage/upload-temp [Cloud Storage Service, Shared Services]
        # Step 3: Create temp file record
        POST /api/files/temp [Util Service, Core Microservices]
        # Step 4: Return temp file metadata and preview URL

--------------------------------------------------------------------------------
API: Upload Domain Media
--------------------------------------------------------------------------------
    POST /merchant/api/v1/domains/:domain_id/media/upload [Seller Admin, Orchestration]

    Description: Move temp file into domain media storage and create a media record. Accepts multipart or JSON reference to `file_id`.

    Request Body (JSON): { "file_id": "file_tmp_123", "path": "banners/home/" }

    Response: 201 Created with media metadata and CDN URL
        {
            "media_id": "media_670d0ca92aa2235ab22abcd",
            "domain_id": "670d0ca92aa2235ab2272e79",
            "file_name": "tpwz51gYRxqSi6kwR7Qqtw.png",
            "path": "banners/home/tpwz51gYRxqSi6kwR7Qqtw.png",
            "cdn_url": "https://cdn.unizap.ai/domains/670d0ca92aa2235ab2272e79/banners/home/tpwz51gYRxqSi6kwR7Qqtw.png",
            "width": 1200,
            "height": 400,
            "mime_type": "image/png",
            "size": 91804,
            "uploaded_at": "2025-02-20T14:05:00Z",
            "alt_text": "logo.png",
            "metadata": { "original_file_id": "file_tmp_123" }
        }
    Flow Sequence:
        # Step 1: Validate Token and Domain
        # Step 2: Move object from temp bucket to domain bucket
        POST /api/cloud/storage/move [Cloud Storage Service, Shared Services]
        # Step 3: Create Media Record
        POST /api/media [Media Service, Core Microservices]
        # Step 4: Invalidate CDN cache for affected paths
        POST /api/cdn/invalidate [CDN Service, Shared Services]
        # Step 5: Return media metadata

--------------------------------------------------------------------------------
API: List / Create / Delete Media Folders
--------------------------------------------------------------------------------
    GET /merchant/api/v1/domains/:domain_id/media/folders
    POST /merchant/api/v1/domains/:domain_id/media/folders
    DELETE /merchant/api/v1/domains/:domain_id/media/:id

    Description: Folder and file management APIs. Deleting media invalidates CDN cache and updates product references.

    Flow Sequence (List/Create/Delete):
        # Step 1: Validate Token and Domain
        # Step 2 (List): GET /api/media/folders?domain_id=:domain_id [Media Service]
        # Step 2 (Create): POST /api/media/folders [Media Service]
        # Step 2 (Delete): DELETE /api/media/:id [Media Service]
        # Step 3 (Delete): POST /api/cdn/invalidate [CDN Service, Shared Services]
        # Step 4: Update product references if media was used
        POST /api/products/media/remove-reference [Product Service, Core Microservices]