client-home:
  get:
    tags: [Client Home]
    summary: Get the Client Home screen as a guest or client
    description: |
      Returns the Client Home payload used by the mobile and web designs:

      - client greeting and current location when a valid client token is supplied
      - notification, favorite, and business-mode quick status
      - active sliders and active main categories
      - up to 10 newest active premium products as featured ads

      The bearer token is optional. Guests receive empty user/location values,
      zero personal counters, and `isFavorite: false`. A valid client token
      personalizes those fields. Authenticated provider tokens are rejected.
      Product images are reduced to the first image, and raw database documents
      or sensitive user fields are never returned.

      <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=9064-3213&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">Client 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=10227-32828&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Client 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=9064-3213&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: "9064:3213"
      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=10227-32828&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10227:32828"
    operationId: getClientHome
    security:
      - SecretKeyAuth: []
      - SecretKeyAuth: []
        ClientBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    responses:
      '200':
        description: Client Home loaded successfully.
        content:
          application/json:
            schema:
              title: ClientHomeResponse
              type: object
              required: [key, message, status, data]
              additionalProperties: false
              properties:
                key: { type: string, enum: [success], example: success }
                message: { type: string, example: "تم تحميل الصفحة الرئيسية بنجاح" }
                status: { type: integer, enum: [200], example: 200 }
                data:
                  type: object
                  required: [user, accountMode, quickStatus, sliders, categories, featuredAds]
                  additionalProperties: false
                  properties:
                    user:
                      type: object
                      description: Empty id/name/location defaults are returned for guests.
                      required: [id, name, currentLocation]
                      additionalProperties: false
                      properties:
                        id: { type: string, example: "665f1c2a9b4e1d0012ab3401" }
                        name: { type: string, example: "أحمد" }
                        currentLocation:
                          type: object
                          required: [title, description, lat, lng]
                          additionalProperties: false
                          properties:
                            title: { type: string, example: "المنزل" }
                            description: { type: string, example: "الرياض، حي الياسمين" }
                            lat: { type: number, example: 24.8138 }
                            lng: { type: number, example: 46.6388 }
                    accountMode:
                      description: Always present. AccountIdentity-backed clients receive the safe mode object; guests and legacy clients receive null.
                      nullable: true
                      example: null
                      allOf:
                        - $ref: '../openapi.yaml#/components/schemas/AccountMode'
                    quickStatus:
                      type: object
                      description: Personal counters are zero and business mode is false for guests.
                      required: [notificationsCount, favoritesCount, isBusinessModeEnabled]
                      additionalProperties: false
                      properties:
                        notificationsCount:
                          type: integer
                          minimum: 0
                          example: 3
                        favoritesCount:
                          type: integer
                          minimum: 0
                          example: 8
                        isBusinessModeEnabled:
                          type: boolean
                          description: Defaults to false because Client currently has no business-mode field.
                          example: false
                    sliders:
                      type: array
                      items:
                        type: object
                        required: [id, image]
                        additionalProperties: false
                        properties:
                          id: { type: string, example: "665f1c2a9b4e1d0012ab3402" }
                          image:
                            type: string
                            example: "https://example.com/assets/uploads/sliders/home-01.jpg"
                    categories:
                      type: array
                      items:
                        type: object
                        required: [id, name, icon]
                        additionalProperties: false
                        properties:
                          id: { type: string, example: "665f1c2a9b4e1d0012ab3403" }
                          name: { type: string, example: "إلكترونيات" }
                          icon:
                            type: string
                            description: Department image mapped to the Client Home icon field.
                            example: "https://example.com/assets/uploads/departments/electronics.png"
                    featuredAds:
                      type: object
                      required: [title, displayType, items]
                      additionalProperties: false
                      properties:
                        title: { type: string, example: "إعلاناتنا المميزة" }
                        displayType: { type: string, enum: [list], example: list }
                        items:
                          type: array
                          items:
                            type: object
                            required: [id, name, image, total, currency, provider, isFavorite, isFeatured, actions]
                            additionalProperties: false
                            properties:
                              id: { type: string, example: "665f1c2a9b4e1d0012ab3404" }
                              name: { type: string, example: "سماعات سوني" }
                              image:
                                type: string
                                description: The first product image only.
                                example: "https://example.com/assets/uploads/users/providers/products/665f1c2a9b4e1d0012ab3405/product.jpg"
                              total: { type: number, example: 1400 }
                              currency: { type: string, example: "\uFDFC" }
                              provider:
                                type: object
                                required: [id, name, location]
                                additionalProperties: false
                                properties:
                                  id: { type: string, example: "665f1c2a9b4e1d0012ab3405" }
                                  name: { type: string, example: "متجر التقنية" }
                                  location:
                                    type: object
                                    required: [title, description, lat, lng]
                                    additionalProperties: false
                                    properties:
                                      title: { type: string, example: "المتجر" }
                                      description: { type: string, example: "الرياض" }
                                      lat: { type: number, example: 24.7136 }
                                      lng: { type: number, example: 46.6753 }
                              isFavorite: { type: boolean, example: true }
                              isFeatured:
                                type: boolean
                                description: Maps the Product `isPremium` flag.
                                example: true
                              actions:
                                type: object
                                required: [details, chat, hasAiPricing, aiPricing]
                                additionalProperties: false
                                properties:
                                  details: { type: boolean, enum: [true], example: true }
                                  chat: { type: boolean, enum: [true], example: true }
                                  hasAiPricing:
                                    type: boolean
                                    description: >
                                      True exactly when `aiPricing` is a
                                      non-null object.
                                    example: true
                                  aiPricing:
                                    type: object
                                    nullable: true
                                    description: >
                                      AI pricing data linked to this Product
                                      itself, or null when no
                                      `aiPricingRequest` is linked.
                                    required:
                                      [suggestedPrice, priceRangeMin, priceRangeMax]
                                    properties:
                                      suggestedPrice: { type: number, example: 1350 }
                                      priceRangeMin: { type: number, example: 1250 }
                                      priceRangeMax: { type: number, example: 1450 }
            example:
              key: success
              message: "تم تحميل الصفحة الرئيسية بنجاح"
              status: 200
              data:
                user:
                  id: "665f1c2a9b4e1d0012ab3401"
                  name: "أحمد"
                  currentLocation:
                    title: "المنزل"
                    description: "الرياض، حي الياسمين"
                    lat: 24.8138
                    lng: 46.6388
                accountMode:
                  activeMode: client
                  roles: [client, provider]
                  availableModes: [client, provider]
                  canSwitchToClient: true
                  canSwitchToProvider: true
                  providerStatus: accepted
                  clientId: "665f1c2a9b4e1d0012ab3401"
                  providerId: "665f1c2a9b4e1d0012ab3405"
                quickStatus:
                  notificationsCount: 3
                  favoritesCount: 8
                  isBusinessModeEnabled: false
                sliders:
                  - id: "665f1c2a9b4e1d0012ab3402"
                    image: "https://example.com/assets/uploads/sliders/home-01.jpg"
                categories:
                  - id: "665f1c2a9b4e1d0012ab3403"
                    name: "إلكترونيات"
                    icon: "https://example.com/assets/uploads/departments/electronics.png"
                featuredAds:
                  title: "إعلاناتنا المميزة"
                  displayType: list
                  items:
                    - id: "665f1c2a9b4e1d0012ab3404"
                      name: "سماعات سوني"
                      image: "https://example.com/assets/uploads/users/providers/products/665f1c2a9b4e1d0012ab3405/product.jpg"
                      total: 1400
                      currency: "\uFDFC"
                      provider:
                        id: "665f1c2a9b4e1d0012ab3405"
                        name: "متجر التقنية"
                        location:
                          title: "المتجر"
                          description: "الرياض"
                          lat: 24.7136
                          lng: 46.6753
                      isFavorite: true
                      isFeatured: true
                      actions:
                        details: true
                        chat: true
                        hasAiPricing: true
                        aiPricing:
                          suggestedPrice: 1350
                          priceRangeMin: 1250
                          priceRangeMax: 1450
      '400':
        description: Invalid lang or secret-key validation.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example:
              key: fail
              message: "حدث خطأ"
              status: 400
      '419':
        description: An authenticated provider bearer token cannot access Client Home.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example:
              key: unauthorized
              message: "غير مسموح لك بتنفيذ هذا الإجراء"
              status: 419
      '500':
        description: Unexpected server error.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example:
              key: exception
              message: "حدث خطأ، برجاء التواصل مع الدعم"
              status: 500

provider-home:
  get:
    tags: [Provider Home]
    summary: Get provider home screen
    description: |
      Returns the authenticated provider home payload used by mobile and web:

      - provider greeting data with `currentLocation` from the saved provider location
      - quick status (notifications, subscription, order reception, individual mode)
      - cancelled / completed order statistics for the current provider only
      - latest (`new`) orders preview (fixed top 5, no pagination)

      Client bearer tokens are rejected. Sliders are intentionally omitted from this
      contract.

      <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-22765&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">Provider 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-85825&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Provider 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-22765&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:22765"
      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-85825&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10760:85825"
    operationId: getProviderHome
    security:
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    responses:
      '200':
        description: Provider home payload.
        content:
          application/json:
            schema:
              title: ProviderHomeResponse
              type: object
              required: [key, message, status, data]
              properties:
                key: { type: string, enum: [success], example: success }
                message: { type: string, example: الرئيسية }
                status: { type: integer, enum: [200], example: 200 }
                data:
                  type: object
                  required: [provider, accountMode, quickStatus, statistics, latestOrders]
                  additionalProperties: false
                  properties:
                    provider:
                      type: object
                      required: [id, name, currentLocation]
                      additionalProperties: false
                      properties:
                        id: { type: string, example: "665f1c2a9b4e1d0012ab34ce" }
                        name: { type: string, example: "أحمد" }
                        currentLocation:
                          type: object
                          required: [title, description, lat, lng]
                          additionalProperties: false
                          properties:
                            title: { type: string, example: "موقعك الحالي" }
                            description: { type: string, example: "Riyadh, Saudi Arabia" }
                            lat: { type: number, example: 24.7139 }
                            lng: { type: number, example: 46.6751 }
                    accountMode:
                      description: Always present. AccountIdentity-backed providers receive the safe mode object; legacy providers receive null.
                      nullable: true
                      example: null
                      allOf:
                        - $ref: '../openapi.yaml#/components/schemas/AccountMode'
                    quickStatus:
                      type: object
                      required: [notificationsCount, hasActiveSubscription, isReceivingOrders, isIndividualMode]
                      additionalProperties: false
                      properties:
                        notificationsCount: { type: integer, example: 3 }
                        hasActiveSubscription: { type: boolean, example: true }
                        isReceivingOrders: { type: boolean, example: true }
                        isIndividualMode: { type: boolean, example: false }
                    statistics:
                      type: object
                      required: [cancelledOrders, completedOrders]
                      additionalProperties: false
                      properties:
                        cancelledOrders:
                          type: object
                          required: [count, label]
                          properties:
                            count: { type: integer, example: 12 }
                            label: { type: string, example: "طلبات ملغية" }
                        completedOrders:
                          type: object
                          required: [count, label]
                          properties:
                            count: { type: integer, example: 156 }
                            label: { type: string, example: "طلبات منتهية" }
                    latestOrders:
                      type: object
                      required: [title, items]
                      additionalProperties: false
                      properties:
                        title: { type: string, example: "الطلبات الجديدة" }
                        items:
                          type: array
                          maxItems: 5
                          items:
                            type: object
                            required: [id, orderNumber, status, product, total, currency, date, actions]
                            additionalProperties: false
                            properties:
                              id: { type: string, example: "665f1c2a9b4e1d0012ab34cf" }
                              orderNumber: { type: string, example: "#12315" }
                              status:
                                type: object
                                required: [key, label]
                                additionalProperties: false
                                properties:
                                  key: { type: string, example: new }
                                  label: { type: string, example: "جديدة" }
                              product:
                                type: object
                                required: [id, name, image]
                                additionalProperties: false
                                properties:
                                  id: { type: string, example: "665f1c2a9b4e1d0012ab34d0" }
                                  name: { type: string, example: "سماعات سوني" }
                                  image: { type: string, example: "https://example.com/uploads/product.jpg" }
                              total: { type: number, example: 1400 }
                              currency: { type: string, example: "\uFDFC" }
                              date: { type: string, example: "2024-01-20" }
                              actions:
                                type: object
                                required: [details]
                                additionalProperties: false
                                properties:
                                  details: { type: boolean, example: true }
            example:
              key: success
              message: الرئيسية
              status: 200
              data:
                provider:
                  id: "665f1c2a9b4e1d0012ab34ce"
                  name: "أحمد"
                  currentLocation:
                    title: "موقعك الحالي"
                    description: "Riyadh, Saudi Arabia"
                    lat: 24.7139
                    lng: 46.6751
                accountMode:
                  activeMode: provider
                  roles: [client, provider]
                  availableModes: [client, provider]
                  canSwitchToClient: true
                  canSwitchToProvider: true
                  providerStatus: accepted
                  clientId: "665f1c2a9b4e1d0012ab34cd"
                  providerId: "665f1c2a9b4e1d0012ab34ce"
                quickStatus:
                  notificationsCount: 3
                  hasActiveSubscription: true
                  isReceivingOrders: true
                  isIndividualMode: false
                statistics:
                  cancelledOrders:
                    count: 12
                    label: "طلبات ملغية"
                  completedOrders:
                    count: 156
                    label: "طلبات منتهية"
                latestOrders:
                  title: "الطلبات الجديدة"
                  items:
                    - id: "665f1c2a9b4e1d0012ab34cf"
                      orderNumber: "#12315"
                      status:
                        key: new
                        label: "جديدة"
                      product:
                        id: "665f1c2a9b4e1d0012ab34d0"
                        name: "سماعات سوني"
                        image: "https://example.com/uploads/product.jpg"
                      total: 1400
                      currency: "\uFDFC"
                      date: "2024-01-20"
                      actions:
                        details: true
      '419':
        description: Bearer token is missing, invalid, expired, revoked, or belongs to a client.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example:
              key: unauthorized
              message: "غير مسموح لك بتنفيذ هذا الإجراء"
              status: 419
      '423':
        description: The provider account is blocked.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example:
              key: blocked
              message: "حسابك موقوف حالياً"
              status: 423
      '500':
        description: Unexpected server error.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example:
              key: exception
              message: "حدث خطأ، برجاء التواصل مع الدعم"
              status: 500

provider-availability:
  patch:
    tags: [Provider Home]
    summary: Toggle provider order reception
    description: |
      Toggles the authenticated provider's ability to receive new orders.

      - `true` means the provider is available to receive orders.
      - `false` means the provider is not available to receive orders.
      - The provider is resolved from the bearer token; no provider id or state is accepted.
      - Client bearer tokens are rejected and cannot change provider availability.

      <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-22765&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">Provider Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-85825&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Provider 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-22765&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:22765"
      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-85825&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10760:85825"
    operationId: toggleProviderOrderReception
    security:
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    responses:
      '200':
        description: The provider order-reception state was toggled and saved.
        content:
          application/json:
            schema:
              type: object
              required: [key, message, status, data]
              properties:
                key: { type: string, enum: [success], example: success }
                message:
                  type: string
                  example: "تم تحديث حالة استقبال الطلبات بنجاح"
                status: { type: integer, enum: [200], example: 200 }
                data:
                  type: object
                  required: [isAvailable, isAvailableText]
                  properties:
                    isAvailable: { type: boolean, example: true }
                    isAvailableText:
                      type: string
                      example: "متاح لاستقبال الطلبات"
            examples:
              acceptingOrders:
                summary: Provider now accepts orders
                value:
                  key: success
                  message: "تم تحديث حالة استقبال الطلبات بنجاح"
                  status: 200
                  data:
                    isAvailable: true
                    isAvailableText: "متاح لاستقبال الطلبات"
              notAcceptingOrders:
                summary: Provider stopped accepting orders
                value:
                  key: success
                  message: "تم تحديث حالة استقبال الطلبات بنجاح"
                  status: 200
                  data:
                    isAvailable: false
                    isAvailableText: "غير متاح لاستقبال الطلبات"
      '419':
        description: Bearer token is missing, invalid, expired, revoked, or belongs to a client.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example:
              key: unauthorized
              message: "غير مسموح لك بتنفيذ هذا الإجراء"
              status: 419
      '423':
        description: The provider account is blocked.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example:
              key: blocked
              message: "حسابك موقوف حالياً"
              status: 423
      '500':
        description: Unexpected server error.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example:
              key: exception
              message: "حدث خطأ، برجاء التواصل مع الدعم"
              status: 500
