# AI pricing package catalogue (Shared Package).

ai-packegs:
  get:
    tags: [Shared Package]
    summary: List ai-packegs
    description: |
      - Requires an authenticated **client or provider** bearer token (`ClientBearerAuth` or `ProviderBearerAuth`).
      - Paginated catalogue of ai-packegs (`Package` model), sorted by `price` then `duration`.
      - Each card includes UI flags: `currentPackage`, `subscribeButton`.
      - Active same package → `currentPackage: true`, `subscribeButton: false`.
      - Expired same package → `currentPackage: true`, `subscribeButton: true` (renew via subscribe).
      - Re-subscribing to the same package while it is still active is rejected.
      - Supports `page` and `limit`; the response carries the standard `paginate` block.
      - Route aliases: `GET /packages-ai` and `GET /packages` remain available for backward compatibility.

      <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=10792-109725&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=10792-112272&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=10792-109725&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: "10792:109725"
      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=10792-112272&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10792:112272"
    operationId: listAiPackegs
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters: &page-limit
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: page
        in: query
        required: false
        schema: { type: integer, minimum: 1, default: 1 }
      - name: limit
        in: query
        required: false
        schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
    responses:
      '200':
        description: Paginated ai-packegs with `currentPackage` and `subscribeButton` flags.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/PackageListResponse' }
            examples:
              available:
                summary: Package available to subscribe
                value:
                  key: success
                  message: "باقات التسعير AI"
                  status: 200
                  data:
                    - id: "665f1c2a9b4e1d0012ab34a1"
                      name: "باقة شهرية"
                      description: "وصف الباقة"
                      price: 100
                      priceText: "100 ر.س"
                      duration: 1
                      durationText: "1 شهر"
                      type: monthly
                      typeText: "شهرية"
                      status: active
                      isFree: false
                      flagetext: "الأكثر طلباً"
                      features:
                        - id: "665f1c2a9b4e1d0012ab34f1"
                          name: "تحليل الأسعار"
                        - id: "665f1c2a9b4e1d0012ab34f2"
                          name: "اقتراحات ذكية"
                      currentPackage: false
                      subscribeButton: true
                  paginate: { currentPage: 1, lastPage: 1, perPage: 20, total: 1 }
              currentActive:
                summary: Same package still active
                value:
                  key: success
                  message: "باقات التسعير AI"
                  status: 200
                  data:
                    - id: "665f1c2a9b4e1d0012ab34a2"
                      name: "باقة المتجر"
                      description: "باقة مناسبة للمتجر"
                      price: 0
                      priceText: "0 ر.س"
                      duration: 1
                      durationText: "1 شهر"
                      type: monthly
                      typeText: "شهرية"
                      status: active
                      isFree: true
                      flagetext: ""
                      features:
                        - id: "665f1c2a9b4e1d0012ab34f1"
                          name: "تحليل الأسعار"
                      currentPackage: true
                      subscribeButton: false
                  paginate: { currentPage: 1, lastPage: 1, perPage: 20, total: 1 }
              expiredSamePackage:
                summary: Same package expired (renew via subscribe)
                value:
                  key: success
                  message: "باقات التسعير AI"
                  status: 200
                  data:
                    - id: "665f1c2a9b4e1d0012ab34a3"
                      name: "باقة شهرية"
                      description: "وصف الباقة"
                      price: 100
                      priceText: "100 ر.س"
                      duration: 1
                      durationText: "1 شهر"
                      type: monthly
                      typeText: "شهرية"
                      status: active
                      isFree: false
                      flagetext: "الأكثر طلباً"
                      features:
                        - id: "665f1c2a9b4e1d0012ab34f1"
                          name: "تحليل الأسعار"
                      currentPackage: true
                      subscribeButton: true
                  paginate: { currentPage: 1, lastPage: 1, perPage: 20, total: 1 }
      '400':
        description: Pagination validation failed.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples: &pagination-validation-examples
              invalidPage:
                value: { key: fail, message: "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", status: 400 }
              invalidLimit:
                value: { key: fail, message: "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", status: 400 }
      '419':
        description: Bearer token is missing, invalid, expired, or revoked.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "يجب تسجيل الدخول", status: 419 }
      '500': { $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 }
