# Public lookup catalogues managed from the admin dashboard and returned via More/Home.

countries:
  get:
    tags: [Lookups]
    summary: List countries
    description: |
      Paginated catalogue of active, visible countries created by the administration.
      Cities for these countries are listed via `GET /cities`.
    operationId: listCountries
    security:
      - SecretKeyAuth: []
    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 countries.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/CountryListResponse' }
            example:
              key: success
              message: "قائمة الدول"
              status: 200
              data:
                - _id: "665f1c2a9b4e1d0012ab34c1"
                  name: "السعودية"
                  image: "https://example.com/assets/uploads/countries/sa.png"
                  code: "+966"
                  iso: "SA"
                  isVisible: 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 }
      '500': { $ref: '#/shared-server-error' }

cities:
  get:
    tags: [Lookups]
    summary: List cities
    description: |
      Response list of active, visible cities (`City` model) listed right under countries.
      Created by the administration; use after `GET /countries`.
      Route aliases: `GET /countries/cities` and `GET /regions` 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=9967-22050&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=10760-85434&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:
      app: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22050&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      appNodeId: "9967:22050"
      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=10760-85434&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10760:85434"
    operationId: listCities
    security:
      - SecretKeyAuth: []
    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: Cities response list.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/CityListResponse' }
            example:
              key: success
              message: "قائمة المدن"
              status: 200
              data:
                - _id: "665f1c2a9b4e1d0012ab34c2"
                  name: "الرياض"
              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
      '500': { $ref: '#/shared-server-error' }

reasons:
  get:
    tags: [Lookups]
    summary: List support reasons
    description: |
      Response list of available support reasons created by the administration
      (`id` + localized `name` only), with standard `paginate` metadata.
    operationId: listReasons
    security:
      - SecretKeyAuth: []
    parameters: *page-limit
    responses:
      '200':
        description: Support reasons response list.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ReasonListResponse' }
            example:
              key: success
              message: "الأسباب"
              status: 200
              data:
                - { id: "665f1c2a9b4e1d0012ab34d1", name: "مشكلة تقنية" }
              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
      '500': { $ref: '#/shared-server-error' }


payments:
  get:
    tags: [Lookups]
    summary: List payment methods
    description: |
      Authenticated payment-method catalogue selected by the bearer actor.

      - **Client token:** returns all available dashboard payment methods.
      - **Provider token:** returns the `online` payment method only; wallet and cash
        are never included for a Provider actor.
      - Swagger UI provides a Client/Provider token switch and sends only the
        selected authorized token.
      - The response item remains (`id`, localized `name`, `slug`, `image`).

      <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=10245-108872&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=10245-108872&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10245:108872"
    operationId: listPaymentMethods
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters: *page-limit
    responses:
      '200':
        description: Paginated payment methods.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/PaymentMethodListResponse' }
            example:
              key: success
              message: "وسيلة الدفع"
              status: 200
              data:
                - id: "665f1c2a9b4e1d0012ab34f1"
                  name: "الدفع الإلكتروني"
                  slug: "online"
                  image: "https://example.com/assets/uploads/payments/online.png"
              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
      '419': { $ref: '#/shared-unauthorized' }
      '500': { $ref: '#/shared-server-error' }

setting:
  get:
    tags: [Lookups]
    summary: Get application settings
    description: |
      Single settings document created by the administration (not a paginated list).
      Returns public store links, contact channels, branding assets, and feature flags
      used by the mobile/web clients.

      <div class="figma-links"><span>Design:</span><span>كم تسوي (brand)</span></div>
    operationId: getSetting
    security:
      - SecretKeyAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    responses:
      '200':
        description: Application settings object.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/SettingSuccessResponse' }
            example:
              key: success
              message: "الإعدادات"
              status: 200
              data:
                id: "665f1c2a9b4e1d0012ab3401"
                linkAndroid: "https://play.google.com/store/apps/details?id=com.example"
                linkApple: "https://apps.apple.com/app/id000"
                linkWebSite: "https://example.com"
                phone: "0500000000"
                phoneWhats: "0500000000"
                email: "support@example.com"
                siteNameAr: "كم تسوي"
                siteNameEn: "Kam Teswa"
      '500': { $ref: '#/shared-server-error' }

provider-products-non-premium:
  get:
    tags: [Lookups]
    summary: List provider non-premium accepted products
    description: |
      Returns the authenticated provider's products that are accepted and not premium.

      - Provider bearer token only.
      - Client tokens are rejected.
      - Filter: `approvalStatus = accept` and `isPremium = false` for `req.user._id`.
      - Optional query `keyword`: case-insensitive partial match on product `name`.
      - Each item returns only `id` and `name`.

      <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: listProviderNonPremiumProducts
    security:
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: keyword
        in: query
        required: false
        description: Optional search term; filters products by name (case-insensitive partial match).
        schema:
          type: string
          maxLength: 200
        example: محراث
    responses:
      '200':
        description: Non-premium accepted products for the current provider.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ProviderNonPremiumProductsResponse'
            example:
              key: success
              message: تم جلب المنتجات غير المميزة بنجاح
              status: 200
              data:
                - id: "665f1c2a9b4e1d0012ab34a1"
                  name: محراث زراعي يدوي
                - id: "665f1c2a9b4e1d0012ab34a2"
                  name: مضخة ري
      '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' }

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

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 }
