# Notifications paths are relative to the /api server mount.
# Actual backend routes (src/routes/api/MoreRoute/MoreRoute.js):
#   GET    /notifications         — list my notifications (marks the returned page seen)
#   DELETE /notifications         — delete ALL my notifications
#   DELETE /notification?id=...   — delete ONE of my notifications (singular path)
#   GET    /notifications/count   — my unread counter
#   PATCH  /notifications/toggle  — toggle isNotify on my own account
#   GET    /notification-keys     — public catalogue of push-notification keys

notifications:
  get:
    tags: [Notifications]
    summary: List my notifications
    description: |
      - Returns only the authenticated user's notifications (client or provider), newest first.
      - The user is resolved from the bearer token; no user id is accepted from the request.
      - Side effect: the returned page is marked seen and the unread counter is reset to 0.
      - Supports `page` and `limit` pagination; 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=9064-5057&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=10234-47170&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><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22866&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">Provider 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=10760-86107&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Provider Web</a></div>
    x-figma: &notifications-figma
      clientMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9064-5057&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      clientMobileNodeId: "9064:5057"
      clientWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10234-47170&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      clientWebNodeId: "10234:47170"
      providerMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22866&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      providerMobileNodeId: "9967:22866"
      providerWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-86107&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      providerWebNodeId: "10760:86107"
    operationId: listNotifications
    security: &notifications-security
      - SecretKeyAuth: []
        ClientBearerAuth: []
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: page
        in: query
        required: false
        schema: { type: integer, minimum: 1, default: 1 }
        description: Page number.
      - name: limit
        in: query
        required: false
        schema: { type: integer, minimum: 1, default: 20 }
        description: Items per page.
    responses:
      '200':
        description: The authenticated user's notifications, newest first.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/NotificationsListResponse'
            example:
              key: success
              message: "الاشعارات"
              status: 200
              data:
                - id: "665f1c2a9b4e1d0012ab34aa"
                  title: "طلب جديد"
                  message: "لديك طلب جديد رقم 1024"
                  receiver: "665f1c2a9b4e1d0012ab34cd"
                  sender: "665f1c2a9b4e1d0012ab34ce"
                  type: order
                  itemId: "665f1c2a9b4e1d0012ab34ff"
                  productNumber: ""
                  order: "665f1c2a9b4e1d0012ab34ff"
                  timeAdd: "منذ 3 ساعات"
              paginate: { currentPage: 1, lastPage: 3, perPage: 20, total: 45 }
      '419': &notifications-unauthorized
        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': &notifications-server-error
        description: Unexpected server error.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example: { key: exception, message: "حدث خطأ، برجاء التواصل مع الدعم", status: 500 }
  delete:
    tags: [Notifications]
    summary: Delete all my notifications
    description: |
      - Deletes every notification addressed to the authenticated user only.
      - Other users' notifications are never touched; the receiver filter comes from the bearer token.
      <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=9064-5057&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=10234-47170&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><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22866&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">Provider 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=10760-86107&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Provider Web</a></div>
    x-figma: *notifications-figma
    operationId: deleteAllNotifications
    security: *notifications-security
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    responses:
      '200':
        description: All of the authenticated user's notifications were deleted.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/SuccessResponse'
            example: { key: success, message: "تم الحذف بنجاح", status: 200 }
      '419': *notifications-unauthorized
      '500': *notifications-server-error

notification-single:
  delete:
    tags: [Notifications]
    summary: Delete one of my notifications
    description: |
      - Deletes a single notification by `id`, only when it is addressed to the authenticated user.
      - An id that does not exist — or belongs to another user — returns the same `fail` response, so notification ids cannot be probed.
      <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=9064-5057&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=10234-47170&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><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22866&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">Provider 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=10760-86107&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Provider Web</a></div>
    x-figma: *notifications-figma
    operationId: deleteNotification
    security: *notifications-security
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: id
        in: query
        required: true
        schema: { type: string, example: "665f1c2a9b4e1d0012ab34aa" }
        description: Id of the notification to delete. Must belong to the authenticated user.
    responses:
      '200':
        description: The notification was deleted.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/SuccessResponse'
            example: { key: success, message: "تم الحذف بنجاح", status: 200 }
      '400':
        description: Missing/invalid id, or the notification does not exist or is not owned by the authenticated user.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example: { key: fail, message: "الاشعار غير موجود", status: 400 }
      '419': *notifications-unauthorized
      '500': *notifications-server-error

notifications-count:
  get:
    tags: [Notifications]
    summary: Get my unread notifications count
    description: |
      - Returns the authenticated user's own unread counter (`notifyCount`) only.
      - The counter is reset to 0 by `GET /notifications`.
      <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=9064-5057&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=10234-47170&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><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22866&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">Provider 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=10760-86107&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Provider Web</a></div>
    x-figma: *notifications-figma
    operationId: getNotificationsCount
    security: *notifications-security
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    responses:
      '200':
        description: Unread notifications count for the authenticated user.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/NotificationsCountResponse'
            example: { key: success, message: "عدد الاشعارات", status: 200, data: 4 }
      '419': *notifications-unauthorized
      '500': *notifications-server-error

notifications-toggle:
  patch:
    tags: [Notifications]
    summary: Toggle my notifications on/off
    description: |
      - Flips the authenticated user's own `isNotify` flag (enable/disable push notifications).
      - No body is required or consumed; only the token owner's account is changed.
      - Returns the updated safe profile DTO with the new `isNotify` value.
      <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=9064-5057&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=10234-47170&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><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22866&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">Provider 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=10760-86107&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Provider Web</a></div>
    x-figma: *notifications-figma
    operationId: toggleNotifications
    security: *notifications-security
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    responses:
      '200':
        description: isNotify was toggled; the updated profile is returned.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ProfileSuccessResponse'
            example:
              key: success
              message: "تم تحديث حالة الإشعارات"
              status: 200
              data:
                id: "665f1c2a9b4e1d0012ab34cd"
                name: "Example Client"
                avatar: "https://example.com/client-avatar.png"
                countryCode: "+966"
                phone: "0512345678"
                fullPhone: "+9660512345678"
                userType: client
                status: active
                active: true
                isNotify: false
      '419': *notifications-unauthorized
      '500': *notifications-server-error

notification-keys:
  get:
    tags: [Notifications]
    summary: List push-notification keys
    description: |
      - Public static catalogue of push-notification keys and their client-side actions (no user data involved).
      - Actual route name is `/notification-keys` (not `/notifications/key-notifications`).
    operationId: listNotificationKeys
    security:
      - SecretKeyAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    responses:
      '200':
        description: Push-notification key catalogue.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/NotificationKeysResponse'
            example:
              key: success
              message: "مفاتيح الاشعارات"
              status: 200
              data:
                - { key: order, service: "/client/order", action: click, field: "" }
      '500': *notifications-server-error

notifications-broadcast:
  post:
    tags: [Provider Notifications]
    summary: Broadcast notification to all active users
    description: |
      - Requires an authenticated **provider** bearer token only (`ProviderBearerAuth`).
      - Client bearer tokens are rejected.
      - Sends one in-app notification to every client and provider with `status: active` and `active: true`.
      - The sender is excluded from the recipient list.
      - Push delivery respects each recipient's `isNotify` preference (handled by the notification service).
      - Request body is **multipart/form-data** with a single field: `message` (5–2000).
      - The notification title is always the project name taken from settings; it is not accepted from the request.
      - Notification type stored as `admin` (informational; no deep-link action).

      <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-26780&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">Provider 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-100498&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Provider Web</a></div>
    x-figma:
      app: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26780&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      appNodeId: "9967:26780"
      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-100498&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10762:100498"
    operationId: broadcastNotificationToActiveUsers
    security:
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [message]
            additionalProperties: false
            properties:
              message:
                type: string
                minLength: 5
                maxLength: 2000
                description: Notification body shown to recipients. The title is always the project name.
                example: "خصم جديد متاح على منتجات المتجر اليوم."
          example:
            message: "خصم جديد متاح على منتجات المتجر اليوم."
    responses:
      '200':
        description: Broadcast accepted; in-app notifications were created for active recipients.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/BroadcastNotificationResponse' }
            example:
              key: success
              message: "تم إرسال الإشعار للمستخدمين النشطين بنجاح"
              status: 200
              data:
                recipients: 42
                sent: 42
                failed: 0
      '400':
        description: Validation failed or no active recipients exist.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples:
              missingMessage:
                value: { key: fail, message: "نص الإشعار مطلوب", status: 400 }
              noActiveUsers:
                value: { key: fail, message: "لا يوجد مستخدمون نشطون لإرسال الإشعار", status: 400 }
      '419':
        description: Bearer token is missing, invalid, expired, revoked, or belongs to a client.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "يجب تسجيل الدخول", status: 419 }
      '500': *notifications-server-error
