openapi: 3.0.0
paths:
  /:
    get:
      operationId: AppController_getHomePage
      parameters: []
      responses:
        '200':
          description: Returns the consumer-facing HTML guide page.
          content:
            text/html:
              schema:
                type: string
      summary: Consumer guide landing page
      tags:
        - App
  /brand/{appKey}/{filename}:
    get:
      operationId: AppController_serveBrandAsset
      parameters:
        - name: appKey
          required: true
          in: path
          schema:
            type: string
        - name: filename
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
      summary: Serve bundled app brand assets
      tags:
        - App
  /client/donors/auth/request-otp:
    post:
      description: >-
        Accepts Saudi mobile numbers in the format +966500110011. Numbers sent
        as +9660500110011 are normalized to +966500110011 before processing.
      operationId: AuthController_requestAuthOtp
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestAuthOtpDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestAuthOtpResponseDto'
      summary: >-
        Start donor authentication with a phone number, issuing registration or
        login OTP as needed
      tags:
        - Donor Auth
  /client/donors/auth/verify-otp:
    post:
      description: >-
        The phoneNumber field must be a Saudi mobile number in the format
        +966500110011. Numbers sent as +9660500110011 are normalized to
        +966500110011 before verification.
      operationId: AuthController_verifyAuthOtp
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyOtpDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthSessionResponseDto'
      summary: >-
        Verify the latest registration or login OTP for a donor phone number and
        create a session when applicable
      tags:
        - Donor Auth
  /client/donors/auth/refresh:
    post:
      operationId: AuthController_refresh
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshSessionDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthSessionResponseDto'
      summary: Rotate the refresh token and issue a new access token
      tags:
        - Donor Auth
  /client/donors/auth/forgot-password/request-otp:
    post:
      description: >-
        Accepts Saudi mobile numbers in the format +966500110011. Numbers sent
        as +9660500110011 are normalized to +966500110011 before processing.
      operationId: AuthController_requestForgotPasswordOtp
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestForgotPasswordOtpDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForgotPasswordOtpResponseDto'
      summary: Issue a mock forgot-password OTP for a verified donor phone number
      tags:
        - Donor Auth
  /client/donors/auth/forgot-password/verify-otp:
    post:
      description: >-
        The phoneNumber field must be a Saudi mobile number in the format
        +966500110011. Numbers sent as +9660500110011 are normalized to
        +966500110011 before verification.
      operationId: AuthController_verifyForgotPasswordOtp
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyOtpDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForgotPasswordResetTokenResponseDto'
      summary: Verify a forgot-password OTP and issue a short-lived reset token
      tags:
        - Donor Auth
  /client/donors/auth/forgot-password/reset:
    post:
      description: >-
        Requires the resetToken returned by the forgot-password OTP verification
        endpoint.
      operationId: AuthController_resetForgotPassword
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetForgotPasswordDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      summary: Reset the donor password using a verified forgot-password reset token
      tags:
        - Donor Auth
  /client/donors/auth/logout:
    post:
      operationId: AuthController_logout
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Revoke the current authenticated session
      tags:
        - Donor Auth
  /client/donors/me:
    get:
      operationId: AuthController_me
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DonorProfileResponseDto'
      security:
        - bearer: []
      summary: Fetch the current donor profile
      tags:
        - Donor Auth
    patch:
      operationId: AuthController_updateProfile
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        description: Editable donor profile fields with an optional profile image.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                fullName:
                  type: string
                  minLength: 2
                email:
                  type: string
                  format: email
                profileImage:
                  type: string
                  format: binary
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DonorProfileResponseDto'
      security:
        - bearer: []
      summary: Update editable donor profile fields
      tags:
        - Donor Auth
  /client/donors/me/set-password:
    post:
      operationId: AuthController_setPassword
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetPasswordDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Set the donor password for the first time
      tags:
        - Donor Auth
  /client/donors/me/change-password:
    post:
      operationId: AuthController_changePassword
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangePasswordDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Change the donor password using the current password
      tags:
        - Donor Auth
  /client/donors/me/sessions:
    get:
      operationId: AuthController_listSessions
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DonorSessionsListResponseDto'
      security:
        - bearer: []
      summary: List the donor sessions for the authenticated account
      tags:
        - Donor Auth
  /client/donors/me/sessions/{sessionId}:
    delete:
      operationId: AuthController_revokeSession
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: sessionId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Revoke one donor session by ID
      tags:
        - Donor Auth
  /admin/ads:
    post:
      operationId: AdminAdsController_createAd
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                title:
                  type: string
                description:
                  type: string
                linkUrl:
                  type: string
                  format: uri
                status:
                  type: string
                  enum:
                    - DRAFT
                    - PUBLISHED
                    - ENDED
                startDate:
                  type: string
                  format: date-time
                endDate:
                  type: string
                  format: date-time
                image:
                  type: string
                  format: binary
              required:
                - title
                - status
                - startDate
                - image
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdResponseDto'
      security:
        - bearer: []
      summary: Create an advertisement
      tags:
        - Admin Ads
    get:
      operationId: AdminAdsController_listAds
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          schema:
            type: string
        - name: status
          required: false
          in: query
          schema:
            type: string
            enum:
              - DRAFT
              - PUBLISHED
              - ENDED
        - name: startDateFrom
          required: false
          in: query
          schema:
            format: date-time
            type: string
        - name: startDateTo
          required: false
          in: query
          schema:
            format: date-time
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdListResponseDto'
      security:
        - bearer: []
      summary: List advertisements
      tags:
        - Admin Ads
  /admin/ads/{id}:
    get:
      operationId: AdminAdsController_getAd
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdProfileResponseDto'
      security:
        - bearer: []
      summary: Get one advertisement
      tags:
        - Admin Ads
    patch:
      operationId: AdminAdsController_updateAd
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                title:
                  type: string
                description:
                  type: string
                linkUrl:
                  type: string
                  format: uri
                status:
                  type: string
                  enum:
                    - DRAFT
                    - PUBLISHED
                    - ENDED
                startDate:
                  type: string
                  format: date-time
                endDate:
                  type: string
                  format: date-time
                deleteImage:
                  type: boolean
                image:
                  type: string
                  format: binary
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdResponseDto'
      security:
        - bearer: []
      summary: Update an advertisement
      tags:
        - Admin Ads
    delete:
      operationId: AdminAdsController_deleteAd
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Delete an advertisement
      tags:
        - Admin Ads
  /client/ads:
    get:
      operationId: ClientAdsController_listAds
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdListResponseDto'
      summary: List published advertisements for app and website banners
      tags:
        - Client Ads
  /admin/admins/auth/login:
    post:
      operationId: AdminAuthController_login
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginAdminDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminAuthSessionResponseDto'
      summary: Sign in with admin email and password
      tags:
        - Admin Auth
  /admin/admins/auth/refresh:
    post:
      operationId: AdminAuthController_refresh
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshAdminSessionDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminAuthSessionResponseDto'
      summary: Rotate the admin refresh token and access token
      tags:
        - Admin Auth
  /admin/admins/auth/forgot-password/request-otp:
    post:
      operationId: AdminAuthController_requestForgotPasswordOtp
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestAdminForgotPasswordOtpDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminForgotPasswordOtpRequestResponseDto'
      summary: Send a forgot-password email OTP to an admin
      tags:
        - Admin Auth
  /admin/admins/auth/forgot-password/verify-otp:
    post:
      operationId: AdminAuthController_verifyForgotPasswordOtp
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyAdminForgotPasswordOtpDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminForgotPasswordResetTokenResponseDto'
      summary: Verify the admin email OTP and issue a reset token
      tags:
        - Admin Auth
  /admin/admins/auth/forgot-password/reset:
    post:
      operationId: AdminAuthController_resetForgotPassword
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetAdminForgotPasswordDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      summary: Reset the admin password with a verified reset token
      tags:
        - Admin Auth
  /admin/admins/auth/logout:
    post:
      operationId: AdminAuthController_logout
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Log out the current admin session
      tags:
        - Admin Auth
  /admin/admins/me:
    get:
      operationId: AdminAuthController_me
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminProfileResponseDto'
      security:
        - bearer: []
      summary: Get the current admin profile
      tags:
        - Admin Auth
    patch:
      operationId: AdminAuthController_updateProfile
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                fullName:
                  type: string
                phoneNumber:
                  type: string
                deleteProfileImage:
                  type: boolean
                profileImage:
                  type: string
                  format: binary
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminProfileResponseDto'
      security:
        - bearer: []
      summary: Update the current admin profile
      tags:
        - Admin Auth
  /admin/admins/me/change-password:
    post:
      operationId: AdminAuthController_changePassword
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeAdminPasswordDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Change the current admin password
      tags:
        - Admin Auth
  /admin/admin-roles/permissions:
    get:
      operationId: AdminRolesController_listAvailablePermissions
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminAvailablePermissionsResponseDto'
      security:
        - bearer: []
      summary: List all available admin permissions
      tags:
        - Admin Roles
  /admin/admin-roles:
    post:
      operationId: AdminRolesController_createRole
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRoleDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminRoleResponseDto'
      security:
        - bearer: []
      summary: Create an admin role
      tags:
        - Admin Roles
    get:
      operationId: AdminRolesController_listRoles
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminRoleListResponseDto'
      security:
        - bearer: []
      summary: List admin roles
      tags:
        - Admin Roles
  /admin/admin-roles/{id}:
    get:
      operationId: AdminRolesController_getRole
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminRoleResponseDto'
      security:
        - bearer: []
      summary: Get one admin role
      tags:
        - Admin Roles
    patch:
      operationId: AdminRolesController_updateRole
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRoleDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminRoleResponseDto'
      security:
        - bearer: []
      summary: Update an admin role
      tags:
        - Admin Roles
    delete:
      operationId: AdminRolesController_deleteRole
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Delete an admin role
      tags:
        - Admin Roles
  /admin/admins:
    post:
      operationId: AdminManagementController_createAdmin
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                fullName:
                  type: string
                email:
                  type: string
                  format: email
                phoneNumber:
                  type: string
                roleId:
                  type: string
                  format: uuid
                password:
                  type: string
                profileImage:
                  type: string
                  format: binary
              required:
                - fullName
                - email
                - phoneNumber
                - password
                - roleId
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminResponseDto'
      security:
        - bearer: []
      summary: Create an admin account
      tags:
        - Admin Management
    get:
      operationId: AdminManagementController_listAdmins
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: joiningStatus
          required: false
          in: query
          schema:
            type: string
            enum:
              - JOINED
              - NOT_JOINED
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          schema:
            type: string
        - name: status
          required: false
          in: query
          schema:
            type: string
            enum:
              - ACTIVE
              - SUSPENDED
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminListResponseDto'
      security:
        - bearer: []
      summary: List admin accounts
      tags:
        - Admin Management
  /admin/admins/{id}:
    get:
      operationId: AdminManagementController_getAdmin
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminProfileResponseDto'
      security:
        - bearer: []
      summary: Get one admin account
      tags:
        - Admin Management
    patch:
      operationId: AdminManagementController_updateAdmin
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                fullName:
                  type: string
                email:
                  type: string
                  format: email
                phoneNumber:
                  type: string
                roleId:
                  type: string
                  format: uuid
                deleteProfileImage:
                  type: boolean
                profileImage:
                  type: string
                  format: binary
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminResponseDto'
      security:
        - bearer: []
      summary: Update an admin account
      tags:
        - Admin Management
    delete:
      operationId: AdminManagementController_deleteAdmin
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Delete an admin account
      tags:
        - Admin Management
  /admin/admins/{id}/suspend:
    post:
      operationId: AdminManagementController_suspendAdmin
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Suspend an admin account
      tags:
        - Admin Management
  /admin/admins/{id}/activate:
    post:
      operationId: AdminManagementController_activateAdmin
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Activate an admin account
      tags:
        - Admin Management
  /admin/admins/{id}/resend-invitation:
    post:
      operationId: AdminManagementController_resendInvitation
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Resend admin invitation credentials
      tags:
        - Admin Management
  /admin/campaign-categories:
    post:
      operationId: AdminCampaignCategoriesController_create
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                icon:
                  type: string
                  format: binary
              required:
                - name
                - icon
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignCategoryResponseDto'
      security:
        - bearer: []
      summary: Create a campaign category
      tags:
        - Admin Campaign Categories
    get:
      operationId: AdminCampaignCategoriesController_list
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignCategoryListResponseDto'
      security:
        - bearer: []
      summary: List campaign categories
      tags:
        - Admin Campaign Categories
  /admin/campaign-categories/{id}:
    get:
      operationId: AdminCampaignCategoriesController_get
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignCategoryDetailResponseDto'
      security:
        - bearer: []
      summary: Get one campaign category
      tags:
        - Admin Campaign Categories
    patch:
      operationId: AdminCampaignCategoriesController_update
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                icon:
                  type: string
                  format: binary
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignCategoryResponseDto'
      security:
        - bearer: []
      summary: Update a campaign category
      tags:
        - Admin Campaign Categories
    delete:
      operationId: AdminCampaignCategoriesController_delete
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Delete a campaign category
      tags:
        - Admin Campaign Categories
  /admin/campaigns:
    post:
      operationId: AdminCampaignsController_create
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                categoryId:
                  type: string
                  format: uuid
                creationStatus:
                  type: string
                  enum:
                    - DRAFT
                    - PUBLISHED
                description:
                  type: string
                donationTarget:
                  type: number
                endDate:
                  type: string
                  format: date-time
                image:
                  type: string
                  format: binary
                startDate:
                  type: string
                  format: date-time
                title:
                  type: string
              required:
                - categoryId
                - creationStatus
                - description
                - donationTarget
                - startDate
                - title
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignResponseDto'
      security:
        - bearer: []
      summary: Create a campaign
      tags:
        - Admin Campaign Management
    get:
      operationId: AdminCampaignsController_list
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: categoryId
          required: false
          in: query
          schema:
            format: uuid
            type: string
        - name: endDate
          required: false
          in: query
          schema:
            format: date-time
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          schema:
            type: string
        - name: startDate
          required: false
          in: query
          schema:
            format: date-time
            type: string
        - name: status
          required: false
          in: query
          schema:
            type: string
            enum:
              - DRAFT
              - PUBLISHED
              - STOPPED
              - ENDED
        - name: tillTargetReached
          required: false
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignListResponseDto'
      security:
        - bearer: []
      summary: List campaigns
      tags:
        - Admin Campaign Management
  /admin/campaigns/{id}:
    get:
      operationId: AdminCampaignsController_get
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDetailResponseDto'
      security:
        - bearer: []
      summary: Get one campaign
      tags:
        - Admin Campaign Management
    patch:
      operationId: AdminCampaignsController_update
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                categoryId:
                  type: string
                  format: uuid
                deleteImage:
                  type: boolean
                description:
                  type: string
                donationTarget:
                  type: number
                endDate:
                  type: string
                  format: date-time
                image:
                  type: string
                  format: binary
                startDate:
                  type: string
                  format: date-time
                title:
                  type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignResponseDto'
      security:
        - bearer: []
      summary: Update a campaign
      tags:
        - Admin Campaign Management
    delete:
      operationId: AdminCampaignsController_delete
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Delete an ended or unfunded campaign
      tags:
        - Admin Campaign Management
  /admin/campaigns/{id}/publish:
    post:
      operationId: AdminCampaignsController_publish
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignResponseDto'
      security:
        - bearer: []
      summary: Publish a draft campaign
      tags:
        - Admin Campaign Management
  /admin/campaigns/{id}/stop:
    post:
      operationId: AdminCampaignsController_stop
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignResponseDto'
      security:
        - bearer: []
      summary: Stop a published campaign
      tags:
        - Admin Campaign Management
  /admin/campaigns/{id}/continue:
    post:
      operationId: AdminCampaignsController_continue
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignResponseDto'
      security:
        - bearer: []
      summary: Continue a stopped campaign
      tags:
        - Admin Campaign Management
  /admin/campaigns/{id}/end:
    post:
      operationId: AdminCampaignsController_end
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignResponseDto'
      security:
        - bearer: []
      summary: End a campaign
      tags:
        - Admin Campaign Management
  /admin/campaigns/{id}/expand:
    post:
      operationId: AdminCampaignsController_expand
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExpandCampaignDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignResponseDto'
      security:
        - bearer: []
      summary: Expand a campaign end date
      tags:
        - Admin Campaign Management
  /client/campaign-categories:
    get:
      operationId: ClientCampaignsController_listCategories
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignCategoryListResponseDto'
      summary: List published campaign categories for clients
      tags:
        - Client Campaigns
  /client/campaigns:
    get:
      operationId: ClientCampaignsController_listCampaigns
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: categoryId
          required: false
          in: query
          schema:
            format: uuid
            type: string
        - name: endDate
          required: false
          in: query
          schema:
            format: date-time
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          schema:
            type: string
        - name: startDate
          required: false
          in: query
          schema:
            format: date-time
            type: string
        - name: status
          required: false
          in: query
          schema:
            type: string
            enum:
              - DRAFT
              - PUBLISHED
              - STOPPED
              - ENDED
        - name: tillTargetReached
          required: false
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignListResponseDto'
      summary: List published campaigns for clients
      tags:
        - Client Campaigns
  /client/campaigns/{id}:
    get:
      operationId: ClientCampaignsController_getCampaign
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDetailResponseDto'
      summary: Get one published campaign for clients
      tags:
        - Client Campaigns
  /admin/donors:
    get:
      operationId: AdminDonorsController_listDonors
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          description: Search by donor full name, email, or phone number.
          schema:
            type: string
        - name: status
          required: false
          in: query
          schema:
            type: string
            enum:
              - ACTIVE
              - SUSPENDED
        - name: registrationDateFrom
          required: false
          in: query
          schema:
            format: date-time
            type: string
        - name: registrationDateTo
          required: false
          in: query
          schema:
            format: date-time
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminDonorListResponseDto'
      security:
        - bearer: []
      summary: List donor accounts
      tags:
        - Admin Donor Management
  /admin/donors/{id}:
    get:
      operationId: AdminDonorsController_getDonor
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminDonorProfileResponseDto'
      security:
        - bearer: []
      summary: Get one donor account
      tags:
        - Admin Donor Management
    delete:
      operationId: AdminDonorsController_deleteDonor
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Delete a donor account
      tags:
        - Admin Donor Management
  /admin/donors/{id}/suspend:
    post:
      operationId: AdminDonorsController_suspendDonor
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Suspend a donor account
      tags:
        - Admin Donor Management
  /admin/donors/{id}/activate:
    post:
      operationId: AdminDonorsController_activateDonor
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Activate a donor account
      tags:
        - Admin Donor Management
  /admin/donations/analytics:
    get:
      operationId: AdminDonationsController_getAnalytics
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: dateFrom
          required: false
          in: query
          schema:
            format: date-time
            type: string
        - name: dateTo
          required: false
          in: query
          schema:
            format: date-time
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DonationAnalyticsResponseDto'
      security:
        - bearer: []
      summary: Get donation analytics
      tags:
        - Admin Donations
  /admin/donations:
    get:
      operationId: AdminDonationsController_listDonations
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          description: >-
            Search by receipt reference, donor name, donor email, or donor phone
            number.
          schema:
            type: string
        - name: status
          required: false
          in: query
          schema:
            type: string
            enum:
              - PENDING
              - PAID
              - FAILED
              - CANCELLED
        - name: paymentMethodName
          required: false
          in: query
          schema:
            type: string
        - name: minAmount
          required: false
          in: query
          schema:
            minimum: 0
            type: number
        - name: maxAmount
          required: false
          in: query
          schema:
            minimum: 0
            type: number
        - name: dateFrom
          required: false
          in: query
          schema:
            format: date-time
            type: string
        - name: dateTo
          required: false
          in: query
          schema:
            format: date-time
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminDonationListResponseDto'
      security:
        - bearer: []
      summary: List donations
      tags:
        - Admin Donations
  /admin/donations/{id}:
    get:
      operationId: AdminDonationsController_getDonation
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminDonationDetailResponseDto'
      security:
        - bearer: []
      summary: Get one donation
      tags:
        - Admin Donations
  /admin/donations/{id}/sync-payment:
    post:
      operationId: AdminDonationsController_syncPayment
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminDonationDetailResponseDto'
      security:
        - bearer: []
      summary: Refresh one donation payment status from MyFatoorah
      tags:
        - Admin Donations
  /client/donations/payment-methods:
    get:
      description: >-
        Use this before creating a donation so web and Flutter clients can
        render the enabled payment options.
      operationId: ClientDonationsController_listPaymentMethods
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: amount
          required: true
          in: query
          schema:
            minimum: 0.01
            example: 150
            type: number
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DonationPaymentMethodListResponseDto'
      summary: List available MyFatoorah payment methods
      tags:
        - Client Donations
  /client/donations:
    post:
      description: >-
        Public endpoint for web and Flutter donation checkout. Authentication is
        optional at the product level and not required by this API.
      operationId: ClientDonationsController_createDonation
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDonationDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientDonationCheckoutDetailResponseDto'
      security:
        - bearer: []
      summary: Create a donation checkout session
      tags:
        - Client Donations
  /client/donations/me:
    get:
      operationId: ClientDonationsController_listMyDonations
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: true
          in: query
          schema:
            type: string
        - name: pageSize
          required: true
          in: query
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientDonationHistoryResponseDto'
      security:
        - bearer: []
      summary: List current donor donation history
      tags:
        - Client Donations
  /client/donations/sync-status:
    post:
      description: >-
        Call this after the customer returns to your web page or mobile deep
        link with a PaymentId from MyFatoorah.
      operationId: ClientDonationsController_syncStatus
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncDonationStatusDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientDonationCheckoutDetailResponseDto'
      summary: Sync donation status from MyFatoorah
      tags:
        - Client Donations
  /client/donations/myfatoorah/webhook:
    post:
      operationId: ClientDonationsController_handleWebhook
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      summary: Receive MyFatoorah webhook notifications
      tags:
        - Client Donations
  /client/donations/myfatoorah/callback:
    get:
      operationId: ClientDonationsController_handleMyFatoorahCallback
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: ''
      summary: Handle MyFatoorah browser callback and redirect to the website
      tags:
        - Client Donations
  /client/donations/{id}:
    get:
      operationId: ClientDonationsController_getDonation
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientDonationCheckoutDetailResponseDto'
      summary: Get one donation checkout status by ID
      tags:
        - Client Donations
  /admin/notifications:
    get:
      operationId: AdminNotificationsController_listNotifications
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: isRead
          required: false
          in: query
          schema:
            nullable: true
            type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationListResponseDto'
      security:
        - bearer: []
      summary: List system notifications for the current admin
      tags:
        - Admin Notifications
  /admin/notifications/unread-count:
    get:
      operationId: AdminNotificationsController_getUnreadCount
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationUnreadCountResponseDto'
      security:
        - bearer: []
      summary: Get unread system notification count for the current admin
      tags:
        - Admin Notifications
  /admin/notifications/{id}/read:
    patch:
      operationId: AdminNotificationsController_markAsRead
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Mark one admin system notification as read
      tags:
        - Admin Notifications
  /admin/push-notifications:
    get:
      operationId: AdminPushNotificationsController_listPushNotifications
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          schema:
            type: string
        - name: targetAudience
          required: false
          in: query
          schema:
            type: string
            enum:
              - ALL_DONORS
              - SPECIFIC_CAMPAIGN_DONORS
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushNotificationCampaignListResponseDto'
      security:
        - bearer: []
      summary: List outbound push notification sends
      tags:
        - Admin Push Notifications
    post:
      operationId: AdminPushNotificationsController_sendPushNotification
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendPushNotificationDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushNotificationCampaignDetailResponseDto'
      security:
        - bearer: []
      summary: >-
        Create a donor push notification send and persist notifications for
        target donors
      tags:
        - Admin Push Notifications
  /client/notifications:
    get:
      operationId: ClientNotificationsController_listNotifications
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: isRead
          required: false
          in: query
          schema:
            nullable: true
            type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationListResponseDto'
      security:
        - bearer: []
      summary: List notifications for the current donor
      tags:
        - Client Notifications
  /client/notifications/unread-count:
    get:
      operationId: ClientNotificationsController_getUnreadCount
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationUnreadCountResponseDto'
      security:
        - bearer: []
      summary: Get unread notification count for the current donor
      tags:
        - Client Notifications
  /client/notifications/{id}/read:
    patch:
      operationId: ClientNotificationsController_markAsRead
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Mark one donor notification as read
      tags:
        - Client Notifications
  /client/notifications/devices:
    post:
      operationId: ClientNotificationsController_registerDeviceToken
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterNotificationDeviceTokenDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationDeviceTokenDetailResponseDto'
      security:
        - bearer: []
      summary: Register or refresh a notification device token for the current donor
      tags:
        - Client Notifications
  /client/notifications/devices/{id}:
    delete:
      operationId: ClientNotificationsController_unregisterDeviceToken
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Unregister a notification device token for the current donor
      tags:
        - Client Notifications
  /admin/drivers:
    post:
      operationId: AdminDriversController_createDriver
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                fullName:
                  type: string
                idNumber:
                  type: string
                phoneNumber:
                  type: string
                vehicleType:
                  type: string
                licensePlateNumber:
                  type: string
                password:
                  type: string
                driverLicense:
                  type: string
                  format: binary
                vehicleRegistration:
                  type: string
                  format: binary
              required:
                - fullName
                - idNumber
                - phoneNumber
                - vehicleType
                - licensePlateNumber
                - password
                - driverLicense
                - vehicleRegistration
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverResponseDto'
      security:
        - bearer: []
      summary: Create a driver account
      tags:
        - Admin Drivers
    get:
      operationId: AdminDriversController_listDrivers
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          schema:
            type: string
        - name: status
          required: false
          in: query
          schema:
            type: string
            enum:
              - ACTIVE
              - SUSPENDED
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverListResponseDto'
      security:
        - bearer: []
      summary: List drivers
      tags:
        - Admin Drivers
  /admin/drivers/{id}:
    get:
      operationId: AdminDriversController_getDriver
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverProfileResponseDto'
      security:
        - bearer: []
      summary: Get one driver
      tags:
        - Admin Drivers
    patch:
      operationId: AdminDriversController_updateDriver
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                fullName:
                  type: string
                phoneNumber:
                  type: string
                vehicleType:
                  type: string
                licensePlateNumber:
                  type: string
                driverLicense:
                  type: string
                  format: binary
                vehicleRegistration:
                  type: string
                  format: binary
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverResponseDto'
      security:
        - bearer: []
      summary: Update a driver account
      tags:
        - Admin Drivers
    delete:
      operationId: AdminDriversController_deleteDriver
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Delete a driver account
      tags:
        - Admin Drivers
  /admin/drivers/{id}/suspend:
    post:
      operationId: AdminDriversController_suspendDriver
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Suspend a driver account
      tags:
        - Admin Drivers
  /admin/drivers/{id}/activate:
    post:
      operationId: AdminDriversController_activateDriver
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Activate a driver account
      tags:
        - Admin Drivers
  /driver/drivers/auth/login:
    post:
      operationId: DriverAuthController_login
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DriverLoginDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverAuthSessionResponseDto'
      summary: Sign in as a driver with phone number and password
      tags:
        - Driver Auth
  /driver/drivers/auth/refresh:
    post:
      operationId: DriverAuthController_refresh
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshDriverSessionDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverAuthSessionResponseDto'
      summary: Rotate the driver refresh token and issue a new access token
      tags:
        - Driver Auth
  /driver/drivers/auth/forgot-password/request-otp:
    post:
      operationId: DriverAuthController_requestForgotPasswordOtp
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestDriverForgotPasswordOtpDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverForgotPasswordOtpResponseDto'
      summary: Request a driver forgot-password OTP
      tags:
        - Driver Auth
  /driver/drivers/auth/forgot-password/verify-otp:
    post:
      operationId: DriverAuthController_verifyForgotPasswordOtp
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyDriverForgotPasswordOtpDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverForgotPasswordResetTokenResponseDto'
      summary: Verify a driver forgot-password OTP and issue a reset token
      tags:
        - Driver Auth
  /driver/drivers/auth/forgot-password/reset:
    post:
      operationId: DriverAuthController_resetForgotPassword
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetDriverForgotPasswordDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      summary: Reset the driver password with a verified reset token
      tags:
        - Driver Auth
  /driver/drivers/auth/logout:
    post:
      operationId: DriverAuthController_logout
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Log out the current driver session
      tags:
        - Driver Auth
  /driver/drivers/me:
    get:
      operationId: DriverAuthController_me
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverProfileResponseDto'
      security:
        - bearer: []
      summary: Fetch the current driver profile
      tags:
        - Driver Auth
    patch:
      operationId: DriverAuthController_updateProfile
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                fullName:
                  type: string
                vehicleType:
                  type: string
                licensePlateNumber:
                  type: string
                deleteProfileImage:
                  type: boolean
                profileImage:
                  type: string
                  format: binary
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverProfileResponseDto'
      security:
        - bearer: []
      summary: Update the current driver profile
      tags:
        - Driver Auth
  /driver/drivers/me/change-password:
    post:
      operationId: DriverAuthController_changePassword
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeDriverPasswordDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Change the current driver password
      tags:
        - Driver Auth
  /admin/families:
    get:
      operationId: AdminFamiliesController_listFamilies
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          description: Search by representative name, phone number, or email.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyListResponseDto'
      security:
        - bearer: []
      summary: List accepted families
      tags:
        - Admin Families
  /admin/families/{id}:
    get:
      operationId: AdminFamiliesController_getFamily
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyProfileResponseDto'
      security:
        - bearer: []
      summary: Get one accepted family
      tags:
        - Admin Families
    patch:
      operationId: AdminFamiliesController_updateFamily
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                representativeName:
                  type: string
                phoneNumber:
                  type: string
                email:
                  type: string
                  format: email
                city:
                  type: string
                familyMembersCount:
                  type: number
                situationDescription:
                  type: string
                latitude:
                  type: number
                longitude:
                  type: number
                deleteExistingSupportingDocuments:
                  type: boolean
                supportingDocuments:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyResponseDto'
      security:
        - bearer: []
      summary: Update an accepted family
      tags:
        - Admin Families
    delete:
      operationId: AdminFamiliesController_deleteFamily
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Delete an accepted family
      tags:
        - Admin Families
  /admin/family-requests:
    get:
      operationId: AdminFamilyRequestsController_listFamilyRequests
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          description: Search by representative name, phone number, or email.
          schema:
            type: string
        - name: requestStatus
          required: false
          in: query
          schema:
            type: string
            enum:
              - UNDER_REVIEW
              - ACCEPTED
              - REJECTED
        - name: requestDateFrom
          required: false
          in: query
          schema:
            format: date-time
            type: string
        - name: requestDateTo
          required: false
          in: query
          schema:
            format: date-time
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyRequestListResponseDto'
      security:
        - bearer: []
      summary: List family requests
      tags:
        - Admin Family Requests
  /admin/family-requests/{id}:
    get:
      operationId: AdminFamilyRequestsController_getFamilyRequest
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyRequestProfileResponseDto'
      security:
        - bearer: []
      summary: Get one family request
      tags:
        - Admin Family Requests
  /admin/family-requests/{id}/accept:
    post:
      operationId: AdminFamilyRequestsController_acceptFamilyRequest
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Accept a family request
      tags:
        - Admin Family Requests
  /admin/family-requests/{id}/reject:
    post:
      operationId: AdminFamilyRequestsController_rejectFamilyRequest
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Function'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Reject a family request
      tags:
        - Admin Family Requests
  /client/family-requests:
    post:
      description: >-
        Public endpoint for web and mobile family request forms. Authentication
        is not required.
      operationId: ClientFamilyRequestsController_createFamilyRequest
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                representativeName:
                  type: string
                phoneNumber:
                  type: string
                email:
                  type: string
                  format: email
                city:
                  type: string
                familyMembersCount:
                  type: number
                situationDescription:
                  type: string
                latitude:
                  type: number
                longitude:
                  type: number
                supportingDocuments:
                  type: array
                  items:
                    type: string
                    format: binary
              required:
                - representativeName
                - phoneNumber
                - email
                - city
                - familyMembersCount
                - situationDescription
                - latitude
                - longitude
                - supportingDocuments
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyRequestProfileResponseDto'
      summary: Submit a family support request
      tags:
        - Client Families
  /admin/volunteer-requests:
    get:
      operationId: AdminVolunteerRequestsController_listVolunteerRequests
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          description: Search by volunteer full name, phone number, or email.
          schema:
            type: string
        - name: requestStatus
          required: false
          in: query
          schema:
            type: string
            enum:
              - UNDER_REVIEW
              - ACCEPTED
              - REJECTED
        - name: volunteerType
          required: false
          in: query
          schema:
            type: string
        - name: requestDateFrom
          required: false
          in: query
          schema:
            format: date-time
            type: string
        - name: requestDateTo
          required: false
          in: query
          schema:
            format: date-time
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolunteerRequestListResponseDto'
      security:
        - bearer: []
      summary: List volunteer requests
      tags:
        - Admin Volunteer Requests
  /admin/volunteer-requests/{id}:
    get:
      operationId: AdminVolunteerRequestsController_getVolunteerRequest
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolunteerRequestProfileResponseDto'
      security:
        - bearer: []
      summary: Get one volunteer request
      tags:
        - Admin Volunteer Requests
  /admin/volunteer-requests/{id}/accept:
    post:
      operationId: AdminVolunteerRequestsController_acceptVolunteerRequest
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Accept a volunteer request
      tags:
        - Admin Volunteer Requests
  /admin/volunteer-requests/{id}/reject:
    post:
      operationId: AdminVolunteerRequestsController_rejectVolunteerRequest
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Function'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Reject a volunteer request
      tags:
        - Admin Volunteer Requests
  /admin/volunteers:
    get:
      operationId: AdminVolunteersController_listVolunteers
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          description: Search by volunteer full name, phone number, or email.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolunteerListResponseDto'
      security:
        - bearer: []
      summary: List accepted volunteers
      tags:
        - Admin Volunteers
  /admin/volunteers/{id}:
    get:
      operationId: AdminVolunteersController_getVolunteer
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolunteerProfileResponseDto'
      security:
        - bearer: []
      summary: Get one accepted volunteer
      tags:
        - Admin Volunteers
    patch:
      operationId: AdminVolunteersController_updateVolunteer
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Function'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolunteerResponseDto'
      security:
        - bearer: []
      summary: Update an accepted volunteer
      tags:
        - Admin Volunteers
    delete:
      operationId: AdminVolunteersController_deleteVolunteer
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Delete an accepted volunteer
      tags:
        - Admin Volunteers
  /client/volunteer-requests:
    post:
      description: >-
        Public endpoint for web and mobile volunteer forms. Authentication is
        not required.
      operationId: ClientVolunteerRequestsController_createVolunteerRequest
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVolunteerRequestDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolunteerRequestProfileResponseDto'
      summary: Submit a volunteer request
      tags:
        - Client Volunteers
  /admin/settings:
    get:
      operationId: SettingsController_getSettings
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralSettingsDetailResponseDto'
      security:
        - bearer: []
      summary: Get general platform settings
      tags:
        - Admin Settings
    patch:
      operationId: SettingsController_updateSettings
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                systemNameEn:
                  type: string
                systemNameAr:
                  type: string
                supportEmail:
                  type: string
                  format: email
                supportPhone:
                  type: string
                supportWhatsapp:
                  type: string
                  nullable: true
                addressEn:
                  type: string
                  nullable: true
                addressAr:
                  type: string
                  nullable: true
                facebookUrl:
                  type: string
                  format: uri
                  nullable: true
                instagramUrl:
                  type: string
                  format: uri
                  nullable: true
                xUrl:
                  type: string
                  format: uri
                  nullable: true
                youtubeUrl:
                  type: string
                  format: uri
                  nullable: true
                linkedinUrl:
                  type: string
                  format: uri
                  nullable: true
                defaultCurrencyCode:
                  type: string
                donationAlertThreshold:
                  type: number
                aboutSnippetEn:
                  type: string
                  nullable: true
                aboutSnippetAr:
                  type: string
                  nullable: true
                footerTextEn:
                  type: string
                  nullable: true
                footerTextAr:
                  type: string
                  nullable: true
                deleteLogo:
                  type: boolean
                deleteFavicon:
                  type: boolean
                logo:
                  type: string
                  format: binary
                favicon:
                  type: string
                  format: binary
              required:
                - systemNameEn
                - systemNameAr
                - supportEmail
                - supportPhone
                - defaultCurrencyCode
                - donationAlertThreshold
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralSettingsDetailResponseDto'
      security:
        - bearer: []
      summary: Update general platform settings
      tags:
        - Admin Settings
  /admin/media-videos:
    post:
      operationId: AdminMediaVideosController_createMediaVideo
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMediaVideoDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaVideoResponseDto'
      security:
        - bearer: []
      summary: Create a media center video
      tags:
        - Admin Media Center
    get:
      operationId: AdminMediaVideosController_listMediaVideos
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          schema:
            type: string
        - name: status
          required: false
          in: query
          schema:
            type: string
            enum:
              - DRAFT
              - PUBLISHED
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminMediaVideoListResponseDto'
      security:
        - bearer: []
      summary: List media center videos
      tags:
        - Admin Media Center
  /admin/media-videos/{id}:
    get:
      operationId: AdminMediaVideosController_getMediaVideo
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminMediaVideoDetailResponseDto'
      security:
        - bearer: []
      summary: Get one media center video
      tags:
        - Admin Media Center
    patch:
      operationId: AdminMediaVideosController_updateMediaVideo
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMediaVideoDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaVideoResponseDto'
      security:
        - bearer: []
      summary: Update a media center video
      tags:
        - Admin Media Center
    delete:
      operationId: AdminMediaVideosController_deleteMediaVideo
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Delete a media center video
      tags:
        - Admin Media Center
  /client/media-videos:
    get:
      operationId: ClientMediaVideosController_listMediaVideos
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          schema:
            type: string
        - name: status
          required: false
          in: query
          schema:
            type: string
            enum:
              - DRAFT
              - PUBLISHED
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientMediaVideoListResponseDto'
      summary: List published media center videos
      tags:
        - Client Media Center
  /files/upload:
    post:
      operationId: FilesController_uploadFile
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        description: Multipart upload payload.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
              required:
                - file
      responses:
        '201':
          description: File uploaded successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    example: 7c38a4a1-2c23-4dcb-80b4-9aef6eb0d58f
                  originalFilename:
                    type: string
                    example: contract.pdf
                  filename:
                    type: string
                    example: 7c38a4a1-2c23-4dcb-80b4-9aef6eb0d58f-contract.pdf
                  url:
                    type: string
                    example: /files/7c38a4a1-2c23-4dcb-80b4-9aef6eb0d58f-contract.pdf
                  downloadUrl:
                    type: string
                    example: >-
                      /files/7c38a4a1-2c23-4dcb-80b4-9aef6eb0d58f-contract.pdf/download
      summary: Upload a file to object storage
      tags:
        - Files
  /files/{filename}:
    get:
      operationId: FilesController_getFileByFilename
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: filename
          required: true
          in: path
          description: Generated filename returned at upload time.
          schema:
            example: 7c38a4a1-2c23-4dcb-80b4-9aef6eb0d58f-contract.pdf
            type: string
      responses:
        '302':
          description: Redirects to a signed inline file URL.
        '404':
          description: No file exists for the given filename.
      summary: Serve a stored file by its generated filename
      tags:
        - Files
  /files/{filename}/download:
    get:
      operationId: FilesController_downloadFileByFilename
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: filename
          required: true
          in: path
          description: Generated filename returned at upload time.
          schema:
            example: 7c38a4a1-2c23-4dcb-80b4-9aef6eb0d58f-contract.pdf
            type: string
      responses:
        '302':
          description: Redirects to a signed attachment download URL.
        '404':
          description: No file exists for the given filename.
      summary: Download a stored file by its generated filename
      tags:
        - Files
  /admin/orders:
    post:
      operationId: AdminOrdersController_createOrder
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponseDto'
      security:
        - bearer: []
      summary: Create a delivery order
      tags:
        - Admin Orders
    get:
      operationId: AdminOrdersController_listOrders
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: page
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: pageSize
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/Object'
        - name: search
          required: false
          in: query
          description: Search by order ID or beneficiary family representative name.
          schema:
            type: string
        - name: status
          required: false
          in: query
          schema:
            type: string
            enum:
              - NEW
              - IN_PROGRESS
              - RECEIVED
              - COMPLETED
              - CANCELLED
        - name: deliveryDateFrom
          required: false
          in: query
          schema:
            format: date-time
            type: string
        - name: deliveryDateTo
          required: false
          in: query
          schema:
            format: date-time
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponseDto'
      security:
        - bearer: []
      summary: List delivery orders
      tags:
        - Admin Orders
  /admin/orders/{id}:
    get:
      operationId: AdminOrdersController_getOrder
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderProfileResponseDto'
      security:
        - bearer: []
      summary: Get one delivery order
      tags:
        - Admin Orders
    patch:
      operationId: AdminOrdersController_updateOrder
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrderDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponseDto'
      security:
        - bearer: []
      summary: Update a new delivery order
      tags:
        - Admin Orders
    delete:
      operationId: AdminOrdersController_deleteOrder
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDto'
      security:
        - bearer: []
      summary: Delete a delivery order
      tags:
        - Admin Orders
  /admin/orders/{id}/status:
    post:
      operationId: AdminOrdersController_changeStatus
      parameters:
        - name: Accept-Language
          in: header
          description: >-
            Optional response language for error messages. Supported values: en,
            ar. Defaults to ar.
          required: false
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrderStatusDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponseDto'
      security:
        - bearer: []
      summary: Change delivery order status
      tags:
        - Admin Orders
info:
  title: selsal-api
  description: HTTP API documentation for selsal-api.
  version: 1.0.0
  contact: {}
tags: []
servers:
  - url: http://localhost:3000
    description: Local development
components:
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: opaque
      type: http
  schemas:
    RequestAuthOtpDto:
      type: object
      properties:
        phoneNumber:
          type: string
          description: >-
            Saudi mobile number in the format +966500110011. Numbers sent as
            +9660500110011 are normalized to +966500110011.
          example: '+966500110011'
      required:
        - phoneNumber
    RequestAuthOtpResponseDto:
      type: object
      properties:
        expiresAt:
          type: string
          format: date-time
        flow:
          type: string
          enum:
            - REGISTRATION
            - LOGIN
          example: REGISTRATION
        isNewUser:
          type: boolean
          example: true
        otpCode:
          type: string
          example: '1234'
        otpSent:
          type: boolean
          example: true
        purpose:
          type: string
          enum:
            - REGISTRATION
            - LOGIN
      required:
        - expiresAt
        - flow
        - isNewUser
        - otpCode
        - otpSent
        - purpose
    VerifyOtpDto:
      type: object
      properties:
        phoneNumber:
          type: string
          description: >-
            Saudi mobile number in the format +966500110011. Numbers sent as
            +9660500110011 are normalized to +966500110011.
          example: '+966500110011'
        otpCode:
          type: string
      required:
        - phoneNumber
        - otpCode
    DonorResponseDto:
      type: object
      properties:
        accountStatus:
          type: string
          enum:
            - ACTIVE
            - SUSPENDED
          example: ACTIVE
        createdAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
          nullable: true
        email:
          type: string
          example: tester@example.com
          format: email
          nullable: true
        fullName:
          type: string
          example: Selsal Tester
          nullable: true
        id:
          type: string
          format: uuid
        phoneNumber:
          type: string
          example: '+966500110011'
        phoneVerifiedAt:
          type: string
          format: date-time
          nullable: true
        profileImagePath:
          type: string
          example: /files/profile-image.jpg
          nullable: true
        registrationDate:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - accountStatus
        - createdAt
        - deletedAt
        - email
        - fullName
        - id
        - phoneNumber
        - phoneVerifiedAt
        - profileImagePath
        - registrationDate
        - updatedAt
    DonorSessionResponseDto:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
        deviceInfo:
          type: string
          example: Mozilla/5.0
          nullable: true
        expiresAt:
          type: string
          format: date-time
        id:
          type: string
          format: uuid
        ipAddress:
          type: string
          example: 203.0.113.42
          nullable: true
        revokedAt:
          type: string
          format: date-time
          nullable: true
        userAgent:
          type: string
          example: Mozilla/5.0
          nullable: true
      required:
        - createdAt
        - deviceInfo
        - expiresAt
        - id
        - ipAddress
        - revokedAt
        - userAgent
    AuthSessionResponseDto:
      type: object
      properties:
        accessToken:
          type: string
        accessTokenExpiresAt:
          type: string
          format: date-time
        donor:
          $ref: '#/components/schemas/DonorResponseDto'
        refreshToken:
          type: string
        session:
          $ref: '#/components/schemas/DonorSessionResponseDto'
      required:
        - accessToken
        - accessTokenExpiresAt
        - donor
        - refreshToken
        - session
    RefreshSessionDto:
      type: object
      properties:
        refreshToken:
          type: string
      required:
        - refreshToken
    RequestForgotPasswordOtpDto:
      type: object
      properties:
        phoneNumber:
          type: string
          description: >-
            Saudi mobile number in the format +966500110011. Numbers sent as
            +9660500110011 are normalized to +966500110011.
          example: '+966500110011'
      required:
        - phoneNumber
    ForgotPasswordOtpResponseDto:
      type: object
      properties:
        expiresAt:
          type: string
          format: date-time
        otpCode:
          type: string
          example: '1234'
        purpose:
          type: string
          enum:
            - FORGOT_PASSWORD
      required:
        - expiresAt
        - otpCode
        - purpose
    ForgotPasswordResetTokenResponseDto:
      type: object
      properties:
        expiresAt:
          type: string
          format: date-time
        resetToken:
          type: string
      required:
        - expiresAt
        - resetToken
    ResetForgotPasswordDto:
      type: object
      properties:
        resetToken:
          type: string
          description: >-
            Short-lived token returned by forgot-password OTP verification and
            valid for password reset only.
        newPassword:
          type: string
      required:
        - resetToken
        - newPassword
    SuccessResponseDto:
      type: object
      properties:
        success:
          type: boolean
          example: true
      required:
        - success
    DonorProfileResponseDto:
      type: object
      properties:
        donor:
          $ref: '#/components/schemas/DonorResponseDto'
      required:
        - donor
    SetPasswordDto:
      type: object
      properties:
        password:
          type: string
      required:
        - password
    ChangePasswordDto:
      type: object
      properties:
        currentPassword:
          type: string
        newPassword:
          type: string
      required:
        - currentPassword
        - newPassword
    DonorSessionsListResponseDto:
      type: object
      properties:
        sessions:
          type: array
          items:
            $ref: '#/components/schemas/DonorSessionResponseDto'
      required:
        - sessions
    AdResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        imagePath:
          type: string
        description:
          type: object
        linkUrl:
          type: object
        status:
          type: string
          enum:
            - DRAFT
            - PUBLISHED
            - ENDED
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - title
        - imagePath
        - status
        - startDate
        - endDate
        - createdAt
        - updatedAt
    Object:
      type: object
      properties: {}
    AdListResponseDto:
      type: object
      properties:
        ads:
          type: array
          items:
            $ref: '#/components/schemas/AdResponseDto'
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
      required:
        - ads
        - page
        - pageSize
        - total
    AdProfileResponseDto:
      type: object
      properties:
        ad:
          $ref: '#/components/schemas/AdResponseDto'
      required:
        - ad
    LoginAdminDto:
      type: object
      properties:
        email:
          type: string
          format: email
        password:
          type: string
        rememberMe:
          type: boolean
          default: false
      required:
        - email
        - password
    AdminRoleResponseDto:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
        description:
          type: object
        id:
          type: string
          format: uuid
        isSystem:
          type: boolean
        name:
          type: string
        nameAr:
          type: string
        nameEn:
          type: string
        permissions:
          type: array
          items:
            type: string
            enum:
              - ROLES_CREATE
              - ROLES_READ
              - ROLES_UPDATE
              - ROLES_DELETE
              - ADMINS_CREATE
              - ADMINS_READ
              - ADMINS_UPDATE
              - ADMINS_DELETE
              - CAMPAIGNS_CREATE
              - CAMPAIGNS_READ
              - CAMPAIGNS_UPDATE
              - CAMPAIGNS_DELETE
              - CAMPAIGN_CATEGORIES_CREATE
              - CAMPAIGN_CATEGORIES_READ
              - CAMPAIGN_CATEGORIES_UPDATE
              - CAMPAIGN_CATEGORIES_DELETE
              - USERS_CREATE
              - USERS_READ
              - USERS_UPDATE
              - USERS_DELETE
              - DRIVERS_CREATE
              - DRIVERS_READ
              - DRIVERS_UPDATE
              - DRIVERS_DELETE
              - VOLUNTEER_REQUESTS_CREATE
              - VOLUNTEER_REQUESTS_READ
              - VOLUNTEER_REQUESTS_UPDATE
              - VOLUNTEER_REQUESTS_DELETE
              - VOLUNTEERS_CREATE
              - VOLUNTEERS_READ
              - VOLUNTEERS_UPDATE
              - VOLUNTEERS_DELETE
              - FAMILY_REQUESTS_CREATE
              - FAMILY_REQUESTS_READ
              - FAMILY_REQUESTS_UPDATE
              - FAMILY_REQUESTS_DELETE
              - FAMILIES_CREATE
              - FAMILIES_READ
              - FAMILIES_UPDATE
              - FAMILIES_DELETE
              - ORDERS_CREATE
              - ORDERS_READ
              - ORDERS_UPDATE
              - ORDERS_DELETE
              - ADS_CREATE
              - ADS_READ
              - ADS_UPDATE
              - ADS_DELETE
              - NOTIFICATIONS_CREATE
              - NOTIFICATIONS_READ
              - NOTIFICATIONS_UPDATE
              - NOTIFICATIONS_DELETE
              - DONATIONS_CREATE
              - DONATIONS_READ
              - DONATIONS_UPDATE
              - DONATIONS_DELETE
              - SETTINGS_CREATE
              - SETTINGS_READ
              - SETTINGS_UPDATE
              - SETTINGS_DELETE
        updatedAt:
          type: string
          format: date-time
      required:
        - createdAt
        - id
        - isSystem
        - name
        - nameAr
        - nameEn
        - permissions
        - updatedAt
    AdminResponseDto:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
        deletedAt:
          type: object
        email:
          type: string
          format: email
        firstLoginAt:
          type: string
          format: date-time
          nullable: true
        fullName:
          type: string
        id:
          type: string
          format: uuid
        role:
          $ref: '#/components/schemas/AdminRoleResponseDto'
        joiningStatus:
          type: string
          enum:
            - JOINED
            - NOT_JOINED
        invitedAt:
          type: string
          format: date-time
          nullable: true
        invitationSentCount:
          type: number
        lastLoginAt:
          type: string
          format: date-time
          nullable: true
        phoneNumber:
          type: string
        profileImagePath:
          type: object
        status:
          type: string
          enum:
            - ACTIVE
            - SUSPENDED
        updatedAt:
          type: string
          format: date-time
      required:
        - createdAt
        - email
        - firstLoginAt
        - fullName
        - id
        - role
        - joiningStatus
        - invitedAt
        - invitationSentCount
        - lastLoginAt
        - phoneNumber
        - status
        - updatedAt
    AdminSessionResponseDto:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
        deviceInfo:
          type: string
          example: Desktop Chrome
          nullable: true
        expiresAt:
          type: string
          format: date-time
        id:
          type: string
          format: uuid
        ipAddress:
          type: string
          example: 203.0.113.42
          nullable: true
        rememberMe:
          type: boolean
        revokedAt:
          type: string
          format: date-time
          nullable: true
        userAgent:
          type: string
          example: Mozilla/5.0
          nullable: true
      required:
        - createdAt
        - deviceInfo
        - expiresAt
        - id
        - ipAddress
        - rememberMe
        - revokedAt
        - userAgent
    AdminAuthSessionResponseDto:
      type: object
      properties:
        accessToken:
          type: string
        accessTokenExpiresAt:
          type: string
          format: date-time
        admin:
          $ref: '#/components/schemas/AdminResponseDto'
        refreshToken:
          type: string
        session:
          $ref: '#/components/schemas/AdminSessionResponseDto'
      required:
        - accessToken
        - accessTokenExpiresAt
        - admin
        - refreshToken
        - session
    RefreshAdminSessionDto:
      type: object
      properties:
        refreshToken:
          type: string
      required:
        - refreshToken
    RequestAdminForgotPasswordOtpDto:
      type: object
      properties:
        email:
          type: string
          format: email
      required:
        - email
    AdminForgotPasswordOtpRequestResponseDto:
      type: object
      properties:
        success:
          type: boolean
          example: true
      required:
        - success
    VerifyAdminForgotPasswordOtpDto:
      type: object
      properties:
        email:
          type: string
          format: email
        otpCode:
          type: string
      required:
        - email
        - otpCode
    AdminForgotPasswordResetTokenResponseDto:
      type: object
      properties:
        expiresAt:
          type: string
          format: date-time
        resetToken:
          type: string
      required:
        - expiresAt
        - resetToken
    ResetAdminForgotPasswordDto:
      type: object
      properties:
        confirmPassword:
          type: string
        newPassword:
          type: string
        resetToken:
          type: string
      required:
        - confirmPassword
        - newPassword
        - resetToken
    AdminProfileResponseDto:
      type: object
      properties:
        admin:
          $ref: '#/components/schemas/AdminResponseDto'
      required:
        - admin
    ChangeAdminPasswordDto:
      type: object
      properties:
        confirmPassword:
          type: string
        currentPassword:
          type: string
        newPassword:
          type: string
      required:
        - confirmPassword
        - currentPassword
        - newPassword
    AdminPermissionGroupResponseDto:
      type: object
      properties:
        resource:
          type: string
        permissions:
          type: array
          items:
            type: string
            enum:
              - ROLES_CREATE
              - ROLES_READ
              - ROLES_UPDATE
              - ROLES_DELETE
              - ADMINS_CREATE
              - ADMINS_READ
              - ADMINS_UPDATE
              - ADMINS_DELETE
              - CAMPAIGNS_CREATE
              - CAMPAIGNS_READ
              - CAMPAIGNS_UPDATE
              - CAMPAIGNS_DELETE
              - CAMPAIGN_CATEGORIES_CREATE
              - CAMPAIGN_CATEGORIES_READ
              - CAMPAIGN_CATEGORIES_UPDATE
              - CAMPAIGN_CATEGORIES_DELETE
              - USERS_CREATE
              - USERS_READ
              - USERS_UPDATE
              - USERS_DELETE
              - DRIVERS_CREATE
              - DRIVERS_READ
              - DRIVERS_UPDATE
              - DRIVERS_DELETE
              - VOLUNTEER_REQUESTS_CREATE
              - VOLUNTEER_REQUESTS_READ
              - VOLUNTEER_REQUESTS_UPDATE
              - VOLUNTEER_REQUESTS_DELETE
              - VOLUNTEERS_CREATE
              - VOLUNTEERS_READ
              - VOLUNTEERS_UPDATE
              - VOLUNTEERS_DELETE
              - FAMILY_REQUESTS_CREATE
              - FAMILY_REQUESTS_READ
              - FAMILY_REQUESTS_UPDATE
              - FAMILY_REQUESTS_DELETE
              - FAMILIES_CREATE
              - FAMILIES_READ
              - FAMILIES_UPDATE
              - FAMILIES_DELETE
              - ORDERS_CREATE
              - ORDERS_READ
              - ORDERS_UPDATE
              - ORDERS_DELETE
              - ADS_CREATE
              - ADS_READ
              - ADS_UPDATE
              - ADS_DELETE
              - NOTIFICATIONS_CREATE
              - NOTIFICATIONS_READ
              - NOTIFICATIONS_UPDATE
              - NOTIFICATIONS_DELETE
              - DONATIONS_CREATE
              - DONATIONS_READ
              - DONATIONS_UPDATE
              - DONATIONS_DELETE
              - SETTINGS_CREATE
              - SETTINGS_READ
              - SETTINGS_UPDATE
              - SETTINGS_DELETE
      required:
        - resource
        - permissions
    AdminAvailablePermissionsResponseDto:
      type: object
      properties:
        all:
          type: array
          items:
            type: string
            enum:
              - ROLES_CREATE
              - ROLES_READ
              - ROLES_UPDATE
              - ROLES_DELETE
              - ADMINS_CREATE
              - ADMINS_READ
              - ADMINS_UPDATE
              - ADMINS_DELETE
              - CAMPAIGNS_CREATE
              - CAMPAIGNS_READ
              - CAMPAIGNS_UPDATE
              - CAMPAIGNS_DELETE
              - CAMPAIGN_CATEGORIES_CREATE
              - CAMPAIGN_CATEGORIES_READ
              - CAMPAIGN_CATEGORIES_UPDATE
              - CAMPAIGN_CATEGORIES_DELETE
              - USERS_CREATE
              - USERS_READ
              - USERS_UPDATE
              - USERS_DELETE
              - DRIVERS_CREATE
              - DRIVERS_READ
              - DRIVERS_UPDATE
              - DRIVERS_DELETE
              - VOLUNTEER_REQUESTS_CREATE
              - VOLUNTEER_REQUESTS_READ
              - VOLUNTEER_REQUESTS_UPDATE
              - VOLUNTEER_REQUESTS_DELETE
              - VOLUNTEERS_CREATE
              - VOLUNTEERS_READ
              - VOLUNTEERS_UPDATE
              - VOLUNTEERS_DELETE
              - FAMILY_REQUESTS_CREATE
              - FAMILY_REQUESTS_READ
              - FAMILY_REQUESTS_UPDATE
              - FAMILY_REQUESTS_DELETE
              - FAMILIES_CREATE
              - FAMILIES_READ
              - FAMILIES_UPDATE
              - FAMILIES_DELETE
              - ORDERS_CREATE
              - ORDERS_READ
              - ORDERS_UPDATE
              - ORDERS_DELETE
              - ADS_CREATE
              - ADS_READ
              - ADS_UPDATE
              - ADS_DELETE
              - NOTIFICATIONS_CREATE
              - NOTIFICATIONS_READ
              - NOTIFICATIONS_UPDATE
              - NOTIFICATIONS_DELETE
              - DONATIONS_CREATE
              - DONATIONS_READ
              - DONATIONS_UPDATE
              - DONATIONS_DELETE
              - SETTINGS_CREATE
              - SETTINGS_READ
              - SETTINGS_UPDATE
              - SETTINGS_DELETE
        groups:
          type: array
          items:
            $ref: '#/components/schemas/AdminPermissionGroupResponseDto'
      required:
        - all
        - groups
    CreateRoleDto:
      type: object
      properties:
        description:
          type: string
        name:
          type: string
          description: >-
            Legacy role key. If omitted, the API derives it from the English
            role name.
        nameAr:
          type: string
        nameEn:
          type: string
        permissions:
          type: array
          items:
            type: string
            enum:
              - ROLES_CREATE
              - ROLES_READ
              - ROLES_UPDATE
              - ROLES_DELETE
              - ADMINS_CREATE
              - ADMINS_READ
              - ADMINS_UPDATE
              - ADMINS_DELETE
              - CAMPAIGNS_CREATE
              - CAMPAIGNS_READ
              - CAMPAIGNS_UPDATE
              - CAMPAIGNS_DELETE
              - CAMPAIGN_CATEGORIES_CREATE
              - CAMPAIGN_CATEGORIES_READ
              - CAMPAIGN_CATEGORIES_UPDATE
              - CAMPAIGN_CATEGORIES_DELETE
              - USERS_CREATE
              - USERS_READ
              - USERS_UPDATE
              - USERS_DELETE
              - DRIVERS_CREATE
              - DRIVERS_READ
              - DRIVERS_UPDATE
              - DRIVERS_DELETE
              - VOLUNTEER_REQUESTS_CREATE
              - VOLUNTEER_REQUESTS_READ
              - VOLUNTEER_REQUESTS_UPDATE
              - VOLUNTEER_REQUESTS_DELETE
              - VOLUNTEERS_CREATE
              - VOLUNTEERS_READ
              - VOLUNTEERS_UPDATE
              - VOLUNTEERS_DELETE
              - FAMILY_REQUESTS_CREATE
              - FAMILY_REQUESTS_READ
              - FAMILY_REQUESTS_UPDATE
              - FAMILY_REQUESTS_DELETE
              - FAMILIES_CREATE
              - FAMILIES_READ
              - FAMILIES_UPDATE
              - FAMILIES_DELETE
              - ORDERS_CREATE
              - ORDERS_READ
              - ORDERS_UPDATE
              - ORDERS_DELETE
              - ADS_CREATE
              - ADS_READ
              - ADS_UPDATE
              - ADS_DELETE
              - NOTIFICATIONS_CREATE
              - NOTIFICATIONS_READ
              - NOTIFICATIONS_UPDATE
              - NOTIFICATIONS_DELETE
              - DONATIONS_CREATE
              - DONATIONS_READ
              - DONATIONS_UPDATE
              - DONATIONS_DELETE
              - SETTINGS_CREATE
              - SETTINGS_READ
              - SETTINGS_UPDATE
              - SETTINGS_DELETE
      required:
        - nameAr
        - nameEn
        - permissions
    AdminRoleListResponseDto:
      type: object
      properties:
        page:
          type: number
        pageSize:
          type: number
        roles:
          type: array
          items:
            $ref: '#/components/schemas/AdminRoleResponseDto'
        total:
          type: number
      required:
        - page
        - pageSize
        - roles
        - total
    UpdateRoleDto:
      type: object
      properties:
        description:
          type: string
        name:
          type: string
        nameAr:
          type: string
        nameEn:
          type: string
        permissions:
          type: array
          items:
            type: string
            enum:
              - ROLES_CREATE
              - ROLES_READ
              - ROLES_UPDATE
              - ROLES_DELETE
              - ADMINS_CREATE
              - ADMINS_READ
              - ADMINS_UPDATE
              - ADMINS_DELETE
              - CAMPAIGNS_CREATE
              - CAMPAIGNS_READ
              - CAMPAIGNS_UPDATE
              - CAMPAIGNS_DELETE
              - CAMPAIGN_CATEGORIES_CREATE
              - CAMPAIGN_CATEGORIES_READ
              - CAMPAIGN_CATEGORIES_UPDATE
              - CAMPAIGN_CATEGORIES_DELETE
              - USERS_CREATE
              - USERS_READ
              - USERS_UPDATE
              - USERS_DELETE
              - DRIVERS_CREATE
              - DRIVERS_READ
              - DRIVERS_UPDATE
              - DRIVERS_DELETE
              - VOLUNTEER_REQUESTS_CREATE
              - VOLUNTEER_REQUESTS_READ
              - VOLUNTEER_REQUESTS_UPDATE
              - VOLUNTEER_REQUESTS_DELETE
              - VOLUNTEERS_CREATE
              - VOLUNTEERS_READ
              - VOLUNTEERS_UPDATE
              - VOLUNTEERS_DELETE
              - FAMILY_REQUESTS_CREATE
              - FAMILY_REQUESTS_READ
              - FAMILY_REQUESTS_UPDATE
              - FAMILY_REQUESTS_DELETE
              - FAMILIES_CREATE
              - FAMILIES_READ
              - FAMILIES_UPDATE
              - FAMILIES_DELETE
              - ORDERS_CREATE
              - ORDERS_READ
              - ORDERS_UPDATE
              - ORDERS_DELETE
              - ADS_CREATE
              - ADS_READ
              - ADS_UPDATE
              - ADS_DELETE
              - NOTIFICATIONS_CREATE
              - NOTIFICATIONS_READ
              - NOTIFICATIONS_UPDATE
              - NOTIFICATIONS_DELETE
              - DONATIONS_CREATE
              - DONATIONS_READ
              - DONATIONS_UPDATE
              - DONATIONS_DELETE
              - SETTINGS_CREATE
              - SETTINGS_READ
              - SETTINGS_UPDATE
              - SETTINGS_DELETE
    AdminListResponseDto:
      type: object
      properties:
        admins:
          type: array
          items:
            $ref: '#/components/schemas/AdminResponseDto'
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
      required:
        - admins
        - page
        - pageSize
        - total
    CampaignCategoryResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        iconPath:
          type: string
        name:
          type: string
        campaignsCount:
          type: number
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - iconPath
        - name
        - campaignsCount
        - createdAt
        - updatedAt
    CampaignCategoryListResponseDto:
      type: object
      properties:
        categories:
          type: array
          items:
            $ref: '#/components/schemas/CampaignCategoryResponseDto'
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
      required:
        - categories
        - page
        - pageSize
        - total
    CampaignCategoryDetailResponseDto:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/CampaignCategoryResponseDto'
      required:
        - category
    CampaignListCategoryResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        iconPath:
          type: string
      required:
        - id
        - name
        - iconPath
    CampaignResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
        imagePath:
          type: object
        category:
          $ref: '#/components/schemas/CampaignListCategoryResponseDto'
        donationTarget:
          type: number
        collectedAmount:
          type: number
        remainingAmount:
          type: number
        donorsCount:
          type: number
        averageDonation:
          type: number
        percentageAchieved:
          type: number
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
          nullable: true
        creationStatus:
          type: string
          enum:
            - DRAFT
            - PUBLISHED
        status:
          type: string
          enum:
            - DRAFT
            - PUBLISHED
            - STOPPED
            - ENDED
        isExpanded:
          type: boolean
        expandedAt:
          type: string
          format: date-time
          nullable: true
        previousEndDate:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - title
        - description
        - category
        - donationTarget
        - collectedAmount
        - remainingAmount
        - donorsCount
        - averageDonation
        - percentageAchieved
        - startDate
        - endDate
        - creationStatus
        - status
        - isExpanded
        - expandedAt
        - previousEndDate
        - createdAt
        - updatedAt
    CampaignListResponseDto:
      type: object
      properties:
        campaigns:
          type: array
          items:
            $ref: '#/components/schemas/CampaignResponseDto'
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
      required:
        - campaigns
        - page
        - pageSize
        - total
    CampaignDetailResponseDto:
      type: object
      properties:
        campaign:
          $ref: '#/components/schemas/CampaignResponseDto'
      required:
        - campaign
    ExpandCampaignDto:
      type: object
      properties:
        newEndDate:
          format: date-time
          type: string
          example: '2026-06-15T23:59:59.000Z'
          description: >-
            Must be later than the current endDate. Example: if current endDate
            is 2026-05-31T23:59:59.000Z, use 2026-06-15T23:59:59.000Z.
      required:
        - newEndDate
    AdminDonorResponseDto:
      type: object
      properties:
        accountStatus:
          type: string
          enum:
            - ACTIVE
            - SUSPENDED
          example: ACTIVE
        createdAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
          nullable: true
        email:
          type: string
          example: donor@selsal.com
          format: email
          nullable: true
        fullName:
          type: string
          example: Selsal Donor
          nullable: true
        id:
          type: string
          format: uuid
        lastLoginAt:
          type: string
          format: date-time
          nullable: true
        phoneNumber:
          type: string
          example: '+966500110011'
        phoneVerifiedAt:
          type: string
          format: date-time
          nullable: true
        profileImagePath:
          type: string
          example: /files/profile-image.jpg
          nullable: true
        registrationDate:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - accountStatus
        - createdAt
        - deletedAt
        - email
        - fullName
        - id
        - lastLoginAt
        - phoneNumber
        - phoneVerifiedAt
        - profileImagePath
        - registrationDate
        - updatedAt
    AdminDonorListResponseDto:
      type: object
      properties:
        donors:
          type: array
          items:
            $ref: '#/components/schemas/AdminDonorResponseDto'
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
      required:
        - donors
        - page
        - pageSize
        - total
    AdminDonorDonationHistoryItemDto:
      type: object
      properties:
        amount:
          type: number
        campaignName:
          type: string
        donationDate:
          type: string
          format: date-time
        id:
          type: string
          format: uuid
        receiptReference:
          type: string
      required:
        - amount
        - campaignName
        - donationDate
        - id
        - receiptReference
    AdminDonorProfileResponseDto:
      type: object
      properties:
        donationHistory:
          type: array
          items:
            $ref: '#/components/schemas/AdminDonorDonationHistoryItemDto'
        donor:
          $ref: '#/components/schemas/AdminDonorResponseDto'
        totalDonatedAmount:
          type: number
        totalDonationsCount:
          type: number
      required:
        - donationHistory
        - donor
        - totalDonatedAmount
        - totalDonationsCount
    DonationAnalyticsMetricDto:
      type: object
      properties:
        label:
          type: string
        amount:
          type: number
        count:
          type: number
          nullable: true
      required:
        - label
        - amount
    DonationAnalyticsResponseDto:
      type: object
      properties:
        totalAmount:
          type: number
        totalDonations:
          type: number
        totalDonors:
          type: number
        activeCampaigns:
          type: number
        topFundedCampaign:
          type: string
          nullable: true
        topFundedCampaignAmount:
          type: number
          nullable: true
        monthlyDonations:
          type: array
          items:
            $ref: '#/components/schemas/DonationAnalyticsMetricDto'
        donationsByCampaign:
          type: array
          items:
            $ref: '#/components/schemas/DonationAnalyticsMetricDto'
        donationsByPaymentMethod:
          type: array
          items:
            $ref: '#/components/schemas/DonationAnalyticsMetricDto'
      required:
        - totalAmount
        - totalDonations
        - totalDonors
        - activeCampaigns
        - monthlyDonations
        - donationsByCampaign
        - donationsByPaymentMethod
    DonationCampaignSummaryDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
      required:
        - id
        - title
    DonationDonorSummaryDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          nullable: true
        fullName:
          type: string
        email:
          type: string
          format: email
          nullable: true
        phoneNumber:
          type: string
      required:
        - fullName
        - phoneNumber
    AdminDonationResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        amount:
          type: number
        currencyIso:
          type: string
        channel:
          type: string
          enum:
            - WEB
            - MOBILE
        status:
          type: string
          enum:
            - PENDING
            - PAID
            - FAILED
            - CANCELLED
        provider:
          type: string
          enum:
            - MYFATOORAH
        campaign:
          $ref: '#/components/schemas/DonationCampaignSummaryDto'
        donor:
          $ref: '#/components/schemas/DonationDonorSummaryDto'
        paymentMethodId:
          type: number
        paymentMethodName:
          type: string
          nullable: true
        paymentMethodCode:
          type: string
          nullable: true
        providerInvoiceId:
          type: string
          nullable: true
        providerPaymentId:
          type: string
          nullable: true
        invoiceReference:
          type: string
          nullable: true
        receiptReference:
          type: string
        providerPayload:
          type: object
          nullable: true
        createdAt:
          type: string
          format: date-time
        paidAt:
          type: string
          format: date-time
          nullable: true
        failedAt:
          type: string
          format: date-time
          nullable: true
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - amount
        - currencyIso
        - channel
        - status
        - provider
        - campaign
        - donor
        - paymentMethodId
        - receiptReference
        - createdAt
        - paidAt
        - failedAt
        - updatedAt
    AdminDonationListResponseDto:
      type: object
      properties:
        donations:
          type: array
          items:
            $ref: '#/components/schemas/AdminDonationResponseDto'
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
      required:
        - donations
        - page
        - pageSize
        - total
    AdminDonationDetailResponseDto:
      type: object
      properties:
        donation:
          $ref: '#/components/schemas/AdminDonationResponseDto'
      required:
        - donation
    DonationPaymentMethodResponseDto:
      type: object
      properties:
        paymentMethodId:
          type: number
        paymentMethodNameEn:
          type: string
        paymentMethodNameAr:
          type: string
        paymentMethodCode:
          type: string
        serviceCharge:
          type: number
        totalAmount:
          type: number
        currencyIso:
          type: string
        paymentCurrencyIso:
          type: string
        isDirectPayment:
          type: boolean
        isEmbeddedSupported:
          type: boolean
        imageUrl:
          type: object
      required:
        - paymentMethodId
        - paymentMethodNameEn
        - paymentMethodNameAr
        - paymentMethodCode
        - serviceCharge
        - totalAmount
        - currencyIso
        - paymentCurrencyIso
        - isDirectPayment
        - isEmbeddedSupported
    DonationPaymentMethodListResponseDto:
      type: object
      properties:
        paymentMethods:
          type: array
          items:
            $ref: '#/components/schemas/DonationPaymentMethodResponseDto'
      required:
        - paymentMethods
    CreateDonationItemDto:
      type: object
      properties:
        campaignId:
          type: string
          format: uuid
          example: 880158d7-ec0f-4066-8b99-0308b2c663c7
        amount:
          type: number
          minimum: 0.01
          example: 100
      required:
        - campaignId
        - amount
    CreateDonationDto:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CreateDonationItemDto'
        paymentMethodId:
          type: number
          example: 2
          description: >-
            MyFatoorah payment method ID returned by the payment-methods
            endpoint.
        channel:
          type: string
          enum:
            - WEB
            - MOBILE
          example: WEB
          description: Use WEB for browser clients and MOBILE for Flutter apps.
        successUrl:
          type: string
          example: https://app.selsal.com/donations/result?status=success
          description: >-
            Frontend success URL. MyFatoorah does not allow localhost callback
            domains.
        errorUrl:
          type: string
          example: https://app.selsal.com/donations/result?status=failed
          description: >-
            Frontend failure URL. MyFatoorah does not allow localhost callback
            domains.
      required:
        - items
        - paymentMethodId
        - channel
    ClientDonationCheckoutItemResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        amount:
          type: number
        campaign:
          $ref: '#/components/schemas/DonationCampaignSummaryDto'
        status:
          type: string
          enum:
            - PENDING
            - PAID
            - FAILED
            - CANCELLED
      required:
        - id
        - amount
        - campaign
        - status
    ClientDonationCheckoutResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        totalAmount:
          type: number
        currencyIso:
          type: string
        channel:
          type: string
          enum:
            - WEB
            - MOBILE
        status:
          type: string
          enum:
            - PENDING
            - PAID
            - FAILED
            - CANCELLED
        provider:
          type: string
          enum:
            - MYFATOORAH
        paymentMethodId:
          type: number
        paymentMethodName:
          type: object
        paymentMethodCode:
          type: object
        paymentUrl:
          type: object
        providerInvoiceId:
          type: object
        providerPaymentId:
          type: object
        invoiceReference:
          type: object
        receiptReference:
          type: string
        createdAt:
          type: string
          format: date-time
        paidAt:
          type: string
          format: date-time
          nullable: true
        failedAt:
          type: string
          format: date-time
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/ClientDonationCheckoutItemResponseDto'
      required:
        - id
        - totalAmount
        - currencyIso
        - channel
        - status
        - provider
        - paymentMethodId
        - receiptReference
        - createdAt
        - paidAt
        - failedAt
        - items
    ClientDonationCheckoutDetailResponseDto:
      type: object
      properties:
        checkout:
          $ref: '#/components/schemas/ClientDonationCheckoutResponseDto'
      required:
        - checkout
    ClientDonationHistoryItemResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        amount:
          type: number
        currencyIso:
          type: string
        status:
          type: string
          enum:
            - PENDING
            - PAID
            - FAILED
            - CANCELLED
        campaign:
          $ref: '#/components/schemas/DonationCampaignSummaryDto'
        receiptReference:
          type: string
        createdAt:
          type: string
          format: date-time
        paidAt:
          type: string
          format: date-time
          nullable: true
      required:
        - id
        - amount
        - currencyIso
        - status
        - campaign
        - receiptReference
        - createdAt
        - paidAt
    ClientDonationHistoryResponseDto:
      type: object
      properties:
        donations:
          type: array
          items:
            $ref: '#/components/schemas/ClientDonationHistoryItemResponseDto'
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
        totalPaidAmount:
          type: number
        totalPaidCampaigns:
          type: number
      required:
        - donations
        - page
        - pageSize
        - total
        - totalPaidAmount
        - totalPaidCampaigns
    SyncDonationStatusDto:
      type: object
      properties:
        paymentId:
          type: string
          example: '07076389662322472373'
          description: >-
            PaymentId returned by MyFatoorah in the redirection URL after
            checkout.
      required:
        - paymentId
    NotificationResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        recipientType:
          type: string
          enum:
            - ADMIN
            - DONOR
            - DRIVER
        recipientId:
          type: string
          format: uuid
        title:
          type: string
          nullable: true
        message:
          type: string
        type:
          type: string
          enum:
            - SYSTEM
            - PUSH_BROADCAST
            - DONATION_CONFIRMED
            - CAMPAIGN_GOAL_REACHED
            - CAMPAIGN_PUBLISHED
            - CAMPAIGN_ENDING_SOON
            - ORDER_STATUS_UPDATED
            - VOLUNTEER_REQUEST_RECEIVED
            - FAMILY_REQUEST_RECEIVED
        channel:
          type: string
          enum:
            - IN_APP
            - PUSH
            - EMAIL
        targetType:
          type: string
          enum:
            - DASHBOARD
            - CAMPAIGN
            - DONATION
            - ORDER
            - VOLUNTEER_REQUEST
            - FAMILY_REQUEST
            - PROFILE
            - OTHER
          nullable: true
        targetId:
          type: string
          format: uuid
          nullable: true
        targetPath:
          type: string
          nullable: true
        data:
          type: object
          nullable: true
        isRead:
          type: boolean
        readAt:
          type: string
          format: date-time
          nullable: true
        sourcePushCampaignId:
          type: string
          format: uuid
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - recipientType
        - recipientId
        - message
        - type
        - channel
        - isRead
        - createdAt
        - updatedAt
    NotificationListResponseDto:
      type: object
      properties:
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/NotificationResponseDto'
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
      required:
        - notifications
        - page
        - pageSize
        - total
    NotificationUnreadCountResponseDto:
      type: object
      properties:
        unreadCount:
          type: number
      required:
        - unreadCount
    PushNotificationCampaignResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        createdByAdminId:
          type: string
          format: uuid
        createdByAdminName:
          type: string
        title:
          type: string
        message:
          type: string
        targetAudience:
          type: string
          enum:
            - ALL_DONORS
            - SPECIFIC_CAMPAIGN_DONORS
        campaignId:
          type: string
          format: uuid
          nullable: true
        campaignTitle:
          type: string
          nullable: true
        recipientCount:
          type: number
        deliveredCount:
          type: number
        failedCount:
          type: number
        deliveryStatus:
          type: string
          enum:
            - PENDING
            - SENT
            - PARTIAL
            - FAILED
        providerName:
          type: string
          nullable: true
        providerPayload:
          type: object
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - createdByAdminId
        - createdByAdminName
        - title
        - message
        - targetAudience
        - recipientCount
        - deliveredCount
        - failedCount
        - deliveryStatus
        - createdAt
        - updatedAt
    PushNotificationCampaignListResponseDto:
      type: object
      properties:
        pushNotifications:
          type: array
          items:
            $ref: '#/components/schemas/PushNotificationCampaignResponseDto'
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
      required:
        - pushNotifications
        - page
        - pageSize
        - total
    SendPushNotificationDto:
      type: object
      properties:
        title:
          type: string
          minLength: 3
          maxLength: 100
        message:
          type: string
          maxLength: 500
        targetAudience:
          type: string
          enum:
            - ALL_DONORS
            - SPECIFIC_CAMPAIGN_DONORS
        campaignId:
          type: string
          format: uuid
          nullable: true
      required:
        - title
        - message
        - targetAudience
    PushNotificationCampaignDetailResponseDto:
      type: object
      properties:
        pushNotification:
          $ref: '#/components/schemas/PushNotificationCampaignResponseDto'
      required:
        - pushNotification
    RegisterNotificationDeviceTokenDto:
      type: object
      properties:
        deviceId:
          type: string
        platform:
          type: string
          enum:
            - WEB
            - IOS
            - ANDROID
        token:
          type: string
        locale:
          type: string
      required:
        - deviceId
        - platform
        - token
    NotificationDeviceTokenResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        ownerType:
          type: string
          enum:
            - ADMIN
            - DONOR
            - DRIVER
        ownerId:
          type: string
          format: uuid
        deviceId:
          type: string
        platform:
          type: string
          enum:
            - WEB
            - IOS
            - ANDROID
        token:
          type: string
        locale:
          type: string
          nullable: true
        isActive:
          type: boolean
        lastSeenAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - ownerType
        - ownerId
        - deviceId
        - platform
        - token
        - isActive
        - lastSeenAt
        - createdAt
        - updatedAt
    NotificationDeviceTokenDetailResponseDto:
      type: object
      properties:
        deviceToken:
          $ref: '#/components/schemas/NotificationDeviceTokenResponseDto'
      required:
        - deviceToken
    DriverResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        fullName:
          type: string
        idNumber:
          type: string
        phoneNumber:
          type: string
        vehicleType:
          type: string
        licensePlateNumber:
          type: string
        driverLicensePath:
          type: string
        vehicleRegistrationPath:
          type: string
        profileImagePath:
          type: object
        accountStatus:
          type: string
          enum:
            - ACTIVE
            - SUSPENDED
        activeOrdersCount:
          type: number
        completedOrdersCount:
          type: number
        lastLoginAt:
          type: string
          format: date-time
          nullable: true
        deletedAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - fullName
        - idNumber
        - phoneNumber
        - vehicleType
        - licensePlateNumber
        - driverLicensePath
        - vehicleRegistrationPath
        - accountStatus
        - activeOrdersCount
        - completedOrdersCount
        - lastLoginAt
        - deletedAt
        - createdAt
        - updatedAt
    DriverListResponseDto:
      type: object
      properties:
        drivers:
          type: array
          items:
            $ref: '#/components/schemas/DriverResponseDto'
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
      required:
        - drivers
        - page
        - pageSize
        - total
    DriverProfileResponseDto:
      type: object
      properties:
        driver:
          $ref: '#/components/schemas/DriverResponseDto'
      required:
        - driver
    DriverLoginDto:
      type: object
      properties:
        phoneNumber:
          type: string
          example: '+966500110011'
        password:
          type: string
      required:
        - phoneNumber
        - password
    DriverSessionResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        revokedAt:
          type: string
          format: date-time
          nullable: true
        deviceInfo:
          type: object
        ipAddress:
          type: object
        userAgent:
          type: object
      required:
        - id
        - createdAt
        - expiresAt
        - revokedAt
    DriverAuthSessionResponseDto:
      type: object
      properties:
        accessToken:
          type: string
        accessTokenExpiresAt:
          type: string
          format: date-time
        refreshToken:
          type: string
        driver:
          $ref: '#/components/schemas/DriverResponseDto'
        session:
          $ref: '#/components/schemas/DriverSessionResponseDto'
      required:
        - accessToken
        - accessTokenExpiresAt
        - refreshToken
        - driver
        - session
    RefreshDriverSessionDto:
      type: object
      properties:
        refreshToken:
          type: string
      required:
        - refreshToken
    RequestDriverForgotPasswordOtpDto:
      type: object
      properties:
        phoneNumber:
          type: string
          example: '+966500110011'
      required:
        - phoneNumber
    DriverForgotPasswordOtpResponseDto:
      type: object
      properties:
        expiresAt:
          type: string
          format: date-time
        otpCode:
          type: string
          example: '123456'
      required:
        - expiresAt
        - otpCode
    VerifyDriverForgotPasswordOtpDto:
      type: object
      properties:
        phoneNumber:
          type: string
          example: '+966500110011'
        otpCode:
          type: string
          example: '123456'
      required:
        - phoneNumber
        - otpCode
    DriverForgotPasswordResetTokenResponseDto:
      type: object
      properties:
        expiresAt:
          type: string
          format: date-time
        resetToken:
          type: string
      required:
        - expiresAt
        - resetToken
    ResetDriverForgotPasswordDto:
      type: object
      properties:
        resetToken:
          type: string
        newPassword:
          type: string
        confirmPassword:
          type: string
      required:
        - resetToken
        - newPassword
        - confirmPassword
    ChangeDriverPasswordDto:
      type: object
      properties:
        currentPassword:
          type: string
        newPassword:
          type: string
        confirmPassword:
          type: string
      required:
        - currentPassword
        - newPassword
        - confirmPassword
    FamilyResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        representativeName:
          type: string
        phoneNumber:
          type: string
        email:
          type: string
          format: email
        city:
          type: string
        familyMembersCount:
          type: number
        situationDescription:
          type: string
        supportingDocumentPaths:
          type: array
          items:
            type: string
        latitude:
          type: number
        longitude:
          type: number
        acceptedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - representativeName
        - phoneNumber
        - email
        - city
        - familyMembersCount
        - situationDescription
        - supportingDocumentPaths
        - latitude
        - longitude
        - acceptedAt
        - createdAt
        - updatedAt
    FamilyListResponseDto:
      type: object
      properties:
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
        families:
          type: array
          items:
            $ref: '#/components/schemas/FamilyResponseDto'
      required:
        - page
        - pageSize
        - total
        - families
    FamilyProfileResponseDto:
      type: object
      properties:
        family:
          $ref: '#/components/schemas/FamilyResponseDto'
      required:
        - family
    FamilyRequestResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        representativeName:
          type: string
        phoneNumber:
          type: string
        email:
          type: string
          format: email
        city:
          type: string
        familyMembersCount:
          type: number
        situationDescription:
          type: string
        supportingDocumentPaths:
          type: array
          items:
            type: string
        latitude:
          type: number
        longitude:
          type: number
        requestStatus:
          type: string
          enum:
            - UNDER_REVIEW
            - ACCEPTED
            - REJECTED
        requestDate:
          type: string
          format: date-time
        reviewedAt:
          type: string
          format: date-time
          nullable: true
        rejectionReason:
          type: object
        familyId:
          type: string
          format: uuid
          nullable: true
      required:
        - id
        - representativeName
        - phoneNumber
        - email
        - city
        - familyMembersCount
        - situationDescription
        - supportingDocumentPaths
        - latitude
        - longitude
        - requestStatus
        - requestDate
        - reviewedAt
        - familyId
    FamilyRequestListResponseDto:
      type: object
      properties:
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
        familyRequests:
          type: array
          items:
            $ref: '#/components/schemas/FamilyRequestResponseDto'
      required:
        - page
        - pageSize
        - total
        - familyRequests
    FamilyRequestProfileResponseDto:
      type: object
      properties:
        familyRequest:
          $ref: '#/components/schemas/FamilyRequestResponseDto'
      required:
        - familyRequest
    Function:
      type: object
      properties: {}
    VolunteerRequestResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        fullName:
          type: string
        phoneNumber:
          type: string
        email:
          type: string
          format: email
        city:
          type: string
        skills:
          type: string
        volunteerType:
          type: string
        requestStatus:
          type: string
          enum:
            - UNDER_REVIEW
            - ACCEPTED
            - REJECTED
        requestDate:
          type: string
          format: date-time
        reviewedAt:
          type: string
          format: date-time
          nullable: true
        rejectionReason:
          type: object
        volunteerId:
          type: string
          format: uuid
          nullable: true
      required:
        - id
        - fullName
        - phoneNumber
        - email
        - city
        - skills
        - volunteerType
        - requestStatus
        - requestDate
        - reviewedAt
        - volunteerId
    VolunteerRequestListResponseDto:
      type: object
      properties:
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
        volunteerRequests:
          type: array
          items:
            $ref: '#/components/schemas/VolunteerRequestResponseDto'
      required:
        - page
        - pageSize
        - total
        - volunteerRequests
    VolunteerRequestProfileResponseDto:
      type: object
      properties:
        volunteerRequest:
          $ref: '#/components/schemas/VolunteerRequestResponseDto'
      required:
        - volunteerRequest
    VolunteerResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        fullName:
          type: string
        phoneNumber:
          type: string
        email:
          type: string
          format: email
        city:
          type: string
        skills:
          type: string
        volunteerType:
          type: string
        acceptedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - fullName
        - phoneNumber
        - email
        - city
        - skills
        - volunteerType
        - acceptedAt
        - createdAt
        - updatedAt
    VolunteerListResponseDto:
      type: object
      properties:
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
        volunteers:
          type: array
          items:
            $ref: '#/components/schemas/VolunteerResponseDto'
      required:
        - page
        - pageSize
        - total
        - volunteers
    VolunteerProfileResponseDto:
      type: object
      properties:
        volunteer:
          $ref: '#/components/schemas/VolunteerResponseDto'
      required:
        - volunteer
    CreateVolunteerRequestDto:
      type: object
      properties:
        fullName:
          type: string
          example: Selsal Volunteer
        phoneNumber:
          type: string
          example: '+966500110011'
          description: >-
            Saudi mobile number in the format +966500110011. Numbers sent as
            +9660500110011 are normalized to +966500110011.
        email:
          type: string
          format: email
          example: volunteer@selsal.com
        city:
          type: string
          example: Riyadh
        skills:
          type: string
          example: Community coordination, event support, and family outreach.
        volunteerType:
          type: string
          example: Field Volunteer
      required:
        - fullName
        - phoneNumber
        - email
        - city
        - skills
        - volunteerType
    GeneralSettingsResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        systemNameEn:
          type: string
        systemNameAr:
          type: string
        supportEmail:
          type: string
          format: email
        supportPhone:
          type: string
        supportWhatsapp:
          type: string
          nullable: true
        addressEn:
          type: string
          nullable: true
        addressAr:
          type: string
          nullable: true
        logoPath:
          type: string
          nullable: true
        faviconPath:
          type: string
          nullable: true
        facebookUrl:
          type: string
          nullable: true
        instagramUrl:
          type: string
          nullable: true
        xUrl:
          type: string
          nullable: true
        youtubeUrl:
          type: string
          nullable: true
        linkedinUrl:
          type: string
          nullable: true
        defaultCurrencyCode:
          type: string
        donationAlertThreshold:
          type: number
        aboutSnippetEn:
          type: string
          nullable: true
        aboutSnippetAr:
          type: string
          nullable: true
        footerTextEn:
          type: string
          nullable: true
        footerTextAr:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - systemNameEn
        - systemNameAr
        - supportEmail
        - supportPhone
        - defaultCurrencyCode
        - donationAlertThreshold
        - createdAt
        - updatedAt
    GeneralSettingsDetailResponseDto:
      type: object
      properties:
        settings:
          $ref: '#/components/schemas/GeneralSettingsResponseDto'
      required:
        - settings
    CreateMediaVideoDto:
      type: object
      properties:
        titleEn:
          type: string
          minLength: 3
          maxLength: 120
        titleAr:
          type: string
          minLength: 3
          maxLength: 120
        descriptionEn:
          type: string
          maxLength: 1000
        descriptionAr:
          type: string
          maxLength: 1000
        youtubeUrl:
          type: string
          format: uri
        isPublished:
          type: boolean
          default: false
      required:
        - titleEn
        - titleAr
        - youtubeUrl
    MediaVideoResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        titleEn:
          type: string
        titleAr:
          type: string
        descriptionEn:
          type: object
          nullable: true
        descriptionAr:
          type: object
          nullable: true
        youtubeUrl:
          type: string
        youtubeVideoId:
          type: string
        thumbnailUrl:
          type: string
        isPublished:
          type: boolean
        publishedAt:
          type: object
          format: date-time
          nullable: true
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
      required:
        - id
        - titleEn
        - titleAr
        - descriptionEn
        - descriptionAr
        - youtubeUrl
        - youtubeVideoId
        - thumbnailUrl
        - isPublished
        - publishedAt
        - createdAt
        - updatedAt
    AdminMediaVideoListResponseDto:
      type: object
      properties:
        mediaVideos:
          type: array
          items:
            $ref: '#/components/schemas/MediaVideoResponseDto'
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
      required:
        - mediaVideos
        - page
        - pageSize
        - total
    AdminMediaVideoDetailResponseDto:
      type: object
      properties:
        mediaVideo:
          $ref: '#/components/schemas/MediaVideoResponseDto'
      required:
        - mediaVideo
    UpdateMediaVideoDto:
      type: object
      properties:
        titleEn:
          type: string
          minLength: 3
          maxLength: 120
        titleAr:
          type: string
          minLength: 3
          maxLength: 120
        descriptionEn:
          type: string
          maxLength: 1000
        descriptionAr:
          type: string
          maxLength: 1000
        youtubeUrl:
          type: string
          format: uri
        isPublished:
          type: boolean
          default: false
    ClientMediaVideoListResponseDto:
      type: object
      properties:
        mediaVideos:
          type: array
          items:
            $ref: '#/components/schemas/MediaVideoResponseDto'
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
      required:
        - mediaVideos
        - page
        - pageSize
        - total
    CreateOrderDto:
      type: object
      properties:
        familyId:
          type: string
          format: uuid
        driverId:
          type: string
          format: uuid
        description:
          type: string
          example: Deliver food basket and hygiene supplies.
        deliveryDate:
          format: date-time
          type: string
          example: '2026-05-01T08:00:00.000Z'
      required:
        - familyId
        - driverId
        - description
        - deliveryDate
    OrderFamilyResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        representativeName:
          type: string
        phoneNumber:
          type: string
        email:
          type: string
        city:
          type: string
        familyMembersCount:
          type: number
        situationDescription:
          type: string
        latitude:
          type: number
        longitude:
          type: number
      required:
        - id
        - representativeName
        - phoneNumber
        - email
        - city
        - familyMembersCount
        - situationDescription
        - latitude
        - longitude
    OrderDriverResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        fullName:
          type: string
        phoneNumber:
          type: string
      required:
        - id
        - fullName
        - phoneNumber
    OrderStatusHistoryResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - NEW
            - IN_PROGRESS
            - RECEIVED
            - COMPLETED
            - CANCELLED
        changedByAdminId:
          type: object
          format: uuid
          nullable: true
        note:
          type: object
        changedAt:
          type: string
          format: date-time
      required:
        - id
        - status
        - changedByAdminId
        - changedAt
    OrderResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        description:
          type: string
        deliveryDate:
          type: string
          format: date-time
        status:
          type: string
          enum:
            - NEW
            - IN_PROGRESS
            - RECEIVED
            - COMPLETED
            - CANCELLED
        family:
          $ref: '#/components/schemas/OrderFamilyResponseDto'
        driver:
          $ref: '#/components/schemas/OrderDriverResponseDto'
        createdByAdminId:
          type: object
          format: uuid
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        statusHistory:
          type: array
          items:
            $ref: '#/components/schemas/OrderStatusHistoryResponseDto'
      required:
        - id
        - description
        - deliveryDate
        - status
        - family
        - driver
        - createdByAdminId
        - createdAt
        - updatedAt
        - statusHistory
    OrderListResponseDto:
      type: object
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/OrderResponseDto'
        page:
          type: number
        pageSize:
          type: number
        total:
          type: number
      required:
        - orders
        - page
        - pageSize
        - total
    OrderProfileResponseDto:
      type: object
      properties:
        order:
          $ref: '#/components/schemas/OrderResponseDto'
      required:
        - order
    UpdateOrderDto:
      type: object
      properties:
        driverId:
          type: string
          format: uuid
        description:
          type: string
          example: Deliver food basket and hygiene supplies.
        deliveryDate:
          format: date-time
          type: string
          example: '2026-05-01T08:00:00.000Z'
    UpdateOrderStatusDto:
      type: object
      properties:
        status:
          type: string
          enum:
            - NEW
            - IN_PROGRESS
            - RECEIVED
            - COMPLETED
            - CANCELLED
        note:
          type: string
          example: Driver confirmed delivery.
      required:
        - status
x-error-language-support:
  default: ar
  header: Accept-Language
  supported:
    - en
    - ar