client-favorites:
  get:
    tags: [Client Favorites]
    summary: List client favorite products
    description: |
      Returns the authenticated client's favorite products as product cards.

      - Client bearer token only.
      - Provider tokens are rejected.
      - Pagination uses `page` and `limit` query params.
      - Response `paginate.perPage` mirrors the applied `limit`.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9509-11594&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Client Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10240-48594&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Client Web</a></div>
    x-figma:
      appNodeId: "9509:11594"
      webNodeId: "10240:48594"
    operationId: getClientFavorites
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: page
        in: query
        required: false
        schema: { type: integer, minimum: 1, default: 1 }
      - name: limit
        in: query
        required: false
        schema: { type: integer, minimum: 1, maximum: 20, default: 10 }
    responses:
      '200':
        description: Favorite products list.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ClientFavoritesResponse'
            example:
              key: success
              message: تم بنجاح
              status: 200
              data:
                title: منتجاتك المفضلة
                displayType: list
                items:
                  - id: "665f1c2a9b4e1d0012ab34d0"
                    name: سماعة سوني
                    image: https://example.com/product.jpg
                    total: 1400
                    currency: "\uFDFC"
                    provider:
                      id: "665f1c2a9b4e1d0012ab34ce"
                      name: أحمد محمد
                      location:
                        title: الرياض
                        description: المملكة العربية السعودية
                        lat: 24.7136
                        lng: 46.6753
                    isFavorite: true
                    isFeatured: true
                    actions:
                      details: true
                      chat: true
                      hasAiPricing: true
                      aiPricing:
                        suggestedPrice: 1350
                        priceRangeMin: 1250
                        priceRangeMax: 1450
              paginate:
                currentPage: 1
                lastPage: 1
                perPage: 10
                total: 1
      '400':
        description: Validation error.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example: { key: fail, message: "بيانات التصفح غير صحيحة", status: 400 }
      '419':
        description: Missing/invalid token or provider token used.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example:
              key: unauthorized
              message: غير مسموح لك بتنفيذ هذا الإجراء
              status: 419
      '500':
        description: Server error.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example: { key: exception, message: "حدث خطأ، برجاء التواصل مع الدعم", status: 500 }
  post:
    tags: [Client Favorites]
    summary: Add product to favorites
    description: |
      Adds a product to the authenticated client's favorites.

      - Idempotent: if already favorited, returns success with `isFavorite: true`.
      - Provider tokens are rejected.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9509-11594&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Client Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10240-48594&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Client Web</a></div>
    x-figma:
      appNodeId: "9509:11594"
      webNodeId: "10240:48594"
    operationId: addClientFavorite
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: productId
        in: query
        required: true
        schema:
          type: string
        description: Product ObjectId consumed by the current validator.
    responses:
      '200':
        description: Product favorited (new or already present).
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/AddClientFavoriteResponse'
            examples:
              added:
                value:
                  key: success
                  message: تمت إضافة المنتج إلى المفضلة بنجاح
                  status: 200
                  data: { productId: "665f1c2a9b4e1d0012ab34d0", isFavorite: true }
              alreadyExists:
                value:
                  key: success
                  message: المنتج موجود بالفعل في المفضلة
                  status: 200
                  data: { productId: "665f1c2a9b4e1d0012ab34d0", isFavorite: true }
      '400':
        description: Invalid productId.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example: { key: fail, message: "معرف المنتج غير صالح", status: 400 }
      '404':
        description: Product not found / inactive.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example: { key: fail, message: "المنتج غير موجود", status: 400 }
      '419':
        description: Missing/invalid token or provider token used.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example: { key: unauthorized, message: "غير مسموح لك بتنفيذ هذا الإجراء", status: 419 }
      '500':
        description: Server error.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example: { key: exception, message: "حدث خطأ، برجاء التواصل مع الدعم", status: 500 }
  delete:
    tags: [Client Favorites]
    summary: Remove product from favorites
    description: |
      Removes a product from the authenticated client's favorites.

      - Idempotent: if not favorited, returns success with `isFavorite: false`.
      - Provider tokens are rejected.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9509-11594&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Client Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10240-48594&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Client Web</a></div>
    x-figma:
      appNodeId: "9509:11594"
      webNodeId: "10240:48594"
    operationId: removeClientFavorite
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: productId
        in: query
        required: true
        schema:
          type: string
        description: Product ObjectId consumed by the current validator.
    responses:
      '200':
        description: Product unfavorited (removed or already absent).
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/RemoveClientFavoriteResponse'
            examples:
              removed:
                value:
                  key: success
                  message: تم حذف المنتج من المفضلة بنجاح
                  status: 200
                  data: { productId: "665f1c2a9b4e1d0012ab34d0", isFavorite: false }
              alreadyAbsent:
                value:
                  key: success
                  message: المنتج غير موجود في المفضلة
                  status: 200
                  data: { productId: "665f1c2a9b4e1d0012ab34d0", isFavorite: false }
      '400':
        description: Invalid productId.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example: { key: fail, message: "معرف المنتج غير صالح", status: 400 }
      '419':
        description: Missing/invalid token or provider token used.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example: { key: unauthorized, message: "غير مسموح لك بتنفيذ هذا الإجراء", status: 419 }
      '500':
        description: Server error.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example: { key: exception, message: "حدث خطأ، برجاء التواصل مع الدعم", status: 500 }
