wallet:
  get:
    tags: [Client Wallet]
    x-figma-ref: Wallet
    summary: Get the current wallet balance
    description: |
      Return the wallet balance for the authenticated client.

      - The route is registered after `requireAuth`.
      - `authorize(UserTypeEnum.CLIENT)` rejects provider tokens.
      - The client is resolved from the JWT; no user id is accepted from the request.
      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9468-9228&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10257-120053&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    operationId: getWalletBalance
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    responses:
      '200':
        description: Current wallet balance.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/WalletBalanceResponse'
            examples:
              client:
                summary: Balance returned for the authenticated client
                value:
                  key: success
                  message: "المحفظة"
                  status: 200
                  data:
                    balance: 250
                    balanceText: "250 ﷼"
                    currency: "﷼"
                    currencyCode: SAR
                    currencySymbol: "﷼"
      '419':
        $ref: '#/shared-unauthorized'
      '423':
        $ref: '#/shared-blocked'
      '500':
        $ref: '#/shared-server-error'

wallet-charge:
  patch:
    tags: [Client Wallet]
    x-figma-ref: Wallet
    summary: Charge the current wallet
    description: |
      Add the submitted amount to the authenticated client's wallet.

      - The route is registered after `requireAuth`.
      - `authorize(UserTypeEnum.CLIENT)` rejects provider tokens.
      - `price` must be numeric and greater than zero.
      - The current backend immediately increments `user.balance` and writes a
        `BalanceHistory` charge entry.

      **Security warning:** payment-gateway verification is marked TODO in the
      current backend. Executing this operation against production changes the
      real authenticated account balance immediately.
      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9468-9228&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10257-120053&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    operationId: chargeWallet
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            $ref: '../openapi.yaml#/components/schemas/WalletChargeRequest'
          examples:
            charge:
              summary: Charge the authenticated wallet with 250 SAR
              value:
                price: 250
    responses:
      '200':
        description: Wallet balance was increased successfully.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/WalletBalanceResponse'
            example:
              key: success
              message: "تم شحن المحفظة بنجاح"
              status: 200
              data:
                balance: 500
                balanceText: "500 ﷼"
                currency: "﷼"
                currencyCode: SAR
                currencySymbol: "﷼"
      '400':
        description: The charge amount is missing, non-numeric, or not greater than zero.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse'
            examples:
              required:
                value: { key: fail, message: "سعر الشحن مطلوب", status: 400 }
              invalid:
                value: { key: fail, message: "قيمة شحن المحفظة يجب أن تكون أكبر من الصفر", status: 400 }
      '419':
        $ref: '#/shared-unauthorized'
      '423':
        $ref: '#/shared-blocked'
      '500':
        $ref: '#/shared-server-error'

shared-unauthorized:
  description: Client access token is missing, invalid, expired, revoked, or belongs to another account type.
  content:
    application/json:
      schema:
        $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
      example: { key: unauthorized, message: "يجب تسجيل الدخول", status: 419 }

shared-blocked:
  description: The authenticated client account is blocked.
  content:
    application/json:
      schema:
        $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
      example: { key: blocked, message: "تم إيقاف حسابك", status: 423 }

shared-server-error:
  description: Unexpected server error without a stack trace.
  content:
    application/json:
      schema:
        $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
      example: { key: exception, message: "يرجى التواصل مع المطور", status: 500 }
