# Chat HTTP paths shared by authenticated clients and providers.
# Realtime Socket.IO events are documented under the root Chat tag and in
# docs/CHAT_SOCKET_EVENTS.md. Do not represent them as HTTP paths.

chats:
  get:
    tags: [Chat]
    summary: List chats
    description: |
      - Requires an authenticated client or provider bearer token (same OR pattern as `GET /profile`).
      - Uses the bearer token actor type; client and provider credentials are never mixed.
      - Returns the caller's 1:1 chats (`isGroup: false`), sorted by `updatedAt` descending.
      - Each card includes the other member's `name`/`avatar`, plus `lastMessage` preview and `time`.
      - Supports `page` and `limit`; the response carries the standard `paginate` block.

      <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=9967-27441&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">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=10762-101454&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    x-figma:
      mobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27441&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      mobileNodeId: "9967:27441"
      web: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-101454&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10762:101454"
    operationId: listChats
    security: &chat-security
      - SecretKeyAuth: []
        ClientBearerAuth: []
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters: &page-limit
      - $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: 100, default: 20 }
    responses:
      '200':
        description: Paginated chat list for the authenticated actor.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ChatListResponse' }
            examples:
              client:
                summary: Client bearer token
                value:
                  key: success
                  message: "محادثات"
                  status: 200
                  data:
                    - id: "665f1c2a9b4e1d0012ab34c1"
                      lastMessage: "مرحبا"
                      avatar: "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/providers/665f1c2a9b4e1d0012ab34b1/avatar.png"
                      name: "متجر المثال"
                      time: "03:21 PM"
                  paginate: { currentPage: 1, lastPage: 1, perPage: 20, total: 1 }
              provider:
                summary: Provider bearer token
                value:
                  key: success
                  message: "محادثات"
                  status: 200
                  data:
                    - id: "665f1c2a9b4e1d0012ab34c2"
                      lastMessage: "هل المنتج متوفر؟"
                      avatar: "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/clients/665f1c2a9b4e1d0012ab34b2/avatar.png"
                      name: "عميل المثال"
                      time: "02:10 PM"
                  paginate: { currentPage: 1, lastPage: 1, perPage: 20, total: 1 }
      '400':
        description: Pagination validation failed.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples: &pagination-validation-examples
              invalidPage:
                value: { key: fail, message: "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", status: 400 }
              invalidLimit:
                value: { key: fail, message: "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", status: 400 }
      '419':
        description: Bearer token is missing, invalid, expired, or revoked.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "يجب تسجيل الدخول", status: 419 }
      '500': { $ref: '#/shared-server-error' }

chat-messages:
  get:
    tags: [Chat]
    summary: List chat messages
    description: |
      - Requires an authenticated client or provider bearer token (same OR pattern as `GET /profile`).
      - Uses the bearer token actor type; client and provider credentials are never mixed.
      - Requires chat `id` (MongoId). Optional `msgId` filters to messages older than that id (`_id < msgId`).
      - Paginated with `page`/`limit`, sorted by `createdAt` descending inside the filter window.
      - Response `data` is `{ messages, chat }` where `chat` is the header layout (`name`, `avatar`).

      <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=9967-27895&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">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=10762-102008&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    x-figma:
      mobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27895&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      mobileNodeId: "9967:27895"
      web: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-102008&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10762:102008"
    operationId: listChatMessages
    security: *chat-security
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: id
        in: query
        required: true
        schema: { type: string }
        description: Chat MongoId.
        example: "665f1c2a9b4e1d0012ab34c1"
      - name: msgId
        in: query
        required: false
        schema: { type: string }
        description: Optional cursor — return only messages older than this message id.
        example: "665f1c2a9b4e1d0012ab34d9"
      - 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: 100, default: 20 }
    responses:
      '200':
        description: Paginated messages plus chat header layout.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ChatMessagesResponse' }
            examples:
              client:
                summary: Client bearer token
                value:
                  key: success
                  message: "تفاصيل المحادثة"
                  status: 200
                  data:
                    messages:
                      - id: "665f1c2a9b4e1d0012ab34d1"
                        type: text
                        message: "مرحبا"
                        senderPath: client
                        senderId: "665f1c2a9b4e1d0012ab34b2"
                        senderName: "عميل المثال"
                        senderAvatar: "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/clients/665f1c2a9b4e1d0012ab34b2/avatar.png"
                        date: "منذ دقيقة"
                    chat:
                      name: "متجر المثال"
                      avatar: "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/providers/665f1c2a9b4e1d0012ab34b1/avatar.png"
                  paginate: { currentPage: 1, lastPage: 1, perPage: 20, total: 1 }
              provider:
                summary: Provider bearer token
                value:
                  key: success
                  message: "تفاصيل المحادثة"
                  status: 200
                  data:
                    messages:
                      - id: "665f1c2a9b4e1d0012ab34d2"
                        type: text
                        message: "أهلاً بك"
                        senderPath: provider
                        senderId: "665f1c2a9b4e1d0012ab34b1"
                        senderName: "متجر المثال"
                        senderAvatar: "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/providers/665f1c2a9b4e1d0012ab34b1/avatar.png"
                        date: "منذ دقيقتين"
                    chat:
                      name: "عميل المثال"
                      avatar: "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/clients/665f1c2a9b4e1d0012ab34b2/avatar.png"
                  paginate: { currentPage: 1, lastPage: 1, perPage: 20, total: 1 }
      '400':
        description: Validation failed (chat id / pagination).
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples:
              missingId:
                value: { key: fail, message: "id مطلوب يرجي ادخال البيانات", status: 400 }
              invalidPage:
                value: { key: fail, message: "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", status: 400 }
              invalidLimit:
                value: { key: fail, message: "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", status: 400 }
      '419':
        description: Bearer token is missing, invalid, expired, or revoked.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "يجب تسجيل الدخول", status: 419 }
      '500': { $ref: '#/shared-server-error' }

chat-upload:
  post:
    tags: [Chat]
    summary: Upload a chat image
    description: |
      - Requires an authenticated client or provider bearer token (same OR pattern as `GET /profile`).
      - Uses the bearer token actor type; client and provider credentials are never mixed.
      - Uploads a single chat image attachment.
      - Multipart fields: `id` (chat MongoId), `file` (image binary).
      - Returns `{ url, file }` — filename only is stored on disk; `url` is the public path.

      <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=9967-27895&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">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=10762-101454&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    x-figma:
      mobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27895&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      mobileNodeId: "9967:27895"
      web: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-101454&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10762:101454"
    operationId: uploadChatFile
    security: *chat-security
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [id, file]
            additionalProperties: false
            properties:
              id:
                type: string
                description: Chat MongoId used as the upload folder name.
                example: "665f1c2a9b4e1d0012ab34c1"
              file:
                type: string
                format: binary
                description: Image file uploaded under the form field name `file`.
          example:
            id: "665f1c2a9b4e1d0012ab34c1"
    responses:
      '200':
        description: Image uploaded successfully.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ChatUploadResponse' }
            examples:
              client:
                summary: Client bearer token
                value:
                  key: success
                  message: "تم الرفع بنجاح"
                  status: 200
                  data:
                    url: "https://dashboard.kam-teswa.4hoste.com/assets/uploads/chat/665f1c2a9b4e1d0012ab34c1/image011753500000000.png"
                    file: "image011753500000000.png"
              provider:
                summary: Provider bearer token
                value:
                  key: success
                  message: "تم الرفع بنجاح"
                  status: 200
                  data:
                    url: "https://dashboard.kam-teswa.4hoste.com/assets/uploads/chat/665f1c2a9b4e1d0012ab34c1/image021753500000001.png"
                    file: "image021753500000001.png"
      '400':
        description: Validation failed (`id` / `type`).
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples:
              missingId:
                value: { key: fail, message: "id مطلوب يرجي ادخال البيانات", status: 400 }
              invalidType:
                value: { key: fail, message: "نوع المحادثة غير صالح", status: 400 }
      '419':
        description: Bearer token is missing, invalid, expired, or revoked.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "يجب تسجيل الدخول", status: 419 }
      '500': { $ref: '#/shared-server-error' }

shared-server-error:
  description: Unexpected server error.
  content:
    application/json:
      schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
      example: { key: exception, message: "حدث خطأ ما", status: 500 }
