apply-coupon:
  patch:
    tags: [Shared Package]
    summary: Preview apply coupon on a subscription package
    description: |
      - Requires an authenticated **client or provider** bearer token (`ClientBearerAuth` or `ProviderBearerAuth`) + `secretkey`.
      - Preview only: validates the coupon and returns discounted totals. Does **not** increment `counter`.
      - Send `code` + `packageId` only. The server resolves `packageId` against AI `Package` first, then `PremiumPackage`.
      - If the id is a premium package, **provider only** (clients get `unauthorized`).
      - Free packages (`isFree` or `price <= 0`) reject coupons.
      - After a successful preview, call `POST /subscription` or `POST /premuim-subscription` with:
        - `coupon` = `data.coupon`
        - `totalAfterCoupon` = `data.totalAfterCoupon`
        - `paymentMethod` = `wallet` | `online`

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-24771&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=10764-92406&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    x-figma:
      mobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-24771&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      mobileNodeId: "9967:24771"
      web: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10764-92406&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10764:92406"
    operationId: applyCouponPreview
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            $ref: '../openapi.yaml#/components/schemas/ApplyCouponRequest'
          examples:
            default:
              summary: Preview coupon on a package
              value:
                code: "SAVE20"
                packageId: "665f1c2a9b4e1d0012ab34a1"
        application/json:
          schema:
            $ref: '../openapi.yaml#/components/schemas/ApplyCouponRequest'
          examples:
            default:
              summary: Preview coupon on a package (JSON)
              value:
                code: "SAVE20"
                packageId: "665f1c2a9b4e1d0012ab34a1"
    responses:
      '200':
        description: Coupon is usable; discounted totals returned (counter unchanged).
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ApplyCouponSuccessResponse' }
            examples:
              success:
                value:
                  key: success
                  message: "تم تطبيق الكوبون بنجاح"
                  status: 200
                  data:
                    coupon: "665f1c2a9b4e1d0012ab34c0"
                    code: "SAVE20"
                    packageId: "665f1c2a9b4e1d0012ab34a1"
                    price: 100
                    total: 100
                    discount: 20
                    totalAfterCoupon: 80
                    discountText: "قيمة الخصم"
                    afterDiscountText: "السعر بعد الخصم"
                    beforeDiscountText: "السعر قبل الخصم"
                    currency: "﷼"
      '400':
        description: Coupon invalid, not started, expired, limit reached, free package, or validation failure.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            examples:
              freePackage:
                value: { key: fail, message: "لا يمكن تطبيق الكوبون على باقة مجانية", status: 400 }
              expired:
                value: { key: fail, message: "تم انتهاء صلاحيه الكوبون", status: 400 }
              invalidCode:
                value: { key: fail, message: " كود الكوبون غير صالح يرجي ادخال 6 عناصر", status: 400 }
      '404':
        description: Coupon or package not found.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            examples:
              couponNotFound:
                value: { key: notFound, message: "الكوبون غير موجود", status: 404 }
              packageNotFound:
                value: { key: notFound, message: "الباقه غير موجودة", status: 404 }
      '419':
        description: Bearer token missing/invalid, or client applied coupon on a premium package.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "يجب تسجيل الدخول", status: 419 }
      '500': { $ref: '#/shared-server-error' }

shared-server-error:
  description: Unexpected server error. No stack trace is returned.
  content:
    application/json:
      schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
      example: { key: exception, message: "حدث خطأ ما، يرجى التواصل مع الدعم الفني", status: 500 }
