premuim-subscription:
  post:
    tags: [Provider Package]
    summary: Subscribe to a premium package
    description: |
      - Requires an authenticated **provider** bearer token only (`ProviderBearerAuth`).
      - Request body is **multipart/form-data** with `id` (PremiumPackage id), `paymentMethod` (`wallet` | `online`), and optional `ids` (single product Mongo id, or JSON array of ids).
      - Optional coupon fields: `coupon` + `totalAfterCoupon` (same anti-tamper / consume rules as `POST /subscription`; preview via `PATCH /apply-coupon`).
      - `ids` examples: `6a65c8744274743cf7a7b2bb` or `["6a65c8744274743cf7a7b2bb"]`.
      - Same payment strategies as AI subscribe (`wallet` deducts balance; `online` is a pass-through stub).
      - Free packages (`price: 0`) skip charging and reject coupons.
      - Creates a `PremiumSubscription` row (`userType: provider`) and points `provider.premiumSubscription` at it.
      - If `ids` is sent, every product id must exist and belong to the provider; otherwise the request fails with `400`. Omitting `ids` (or sending empty) is allowed.
      - On success, previously demoted premium products (`premiumSuspended = true`) are restored to `isPremium = true` immediately.
      - On success with valid `ids`, those products are also marked `isPremium = true` (`premiumExpireAt` matches the subscription expiry).
      - Any previous **active** premium subscriptions for the same provider are set to `cancelled` (and their expire cron jobs are cleared) so only one active row exists.
      - When the expire cron runs for the new subscription, its status becomes `expired` and premium products are demoted.

      <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-27997&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-27997&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:27997"
      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: subscribePremiumPackage
    security:
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            $ref: '../openapi.yaml#/components/schemas/PremiumSubscribeRequest'
          examples:
            wallet:
              summary: Pay from wallet
              value:
                id: "665f1c2a9b4e1d0012ab34b2"
                paymentMethod: wallet
                ids: "6a65c8744274743cf7a7b2bb"
            withCoupon:
              summary: Pay with coupon
              value:
                id: "665f1c2a9b4e1d0012ab34b2"
                paymentMethod: wallet
                coupon: "665f1c2a9b4e1d0012ab34c0"
                totalAfterCoupon: 80
            online:
              summary: Pay online (stub)
              value:
                id: "665f1c2a9b4e1d0012ab34b2"
                paymentMethod: online
                ids: '["6a65c8744274743cf7a7b2bb"]'
    responses:
      '200':
        description: Premium subscription created. Previous active premium subscriptions for this provider are cancelled.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/SubscribeSuccessResponse' }
            examples:
              success:
                value:
                  key: success
                  message: "تم الاشتراك بنجاح"
                  status: 200
      '400':
        description: Validation or payment failure.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            examples:
              invalidPayment:
                value: { key: fail, message: "طريقة الدفع غير صحيحة. اختر من [wallet, online]", status: 400 }
              insufficientBalance:
                value: { key: fail, message: "رصيد المحفظة غير كافٍ", status: 400 }
              invalidProductIds:
                value: { key: fail, message: "بعض المنتجات غير موجودة أو لا تخصك", status: 400 }
      '404':
        description: Package not found.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: notFound, message: "الباقه غير موجودة", status: 404 }
      '419':
        description: Bearer token is missing, invalid, expired, revoked, or belongs to a non-provider actor.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "يجب تسجيل الدخول", status: 419 }
      '500': { $ref: '#/shared-server-error' }
