pricing-request-create:
  post:
    tags: [AI Pricing]
    summary: Create an AI pricing request
    description: |
      Submit product name, image, and specifications for AI pricing (Price Request Mechanism).

      - Requires an authenticated **client or provider** bearer token (`ClientBearerAuth` or `ProviderBearerAuth`).
      - Swagger UI exposes a **token switcher** (Client / Provider); only the selected scheme is sent.
      - Multipart body: `name` (required), `image` (required jpeg/jpg/png/webp), `specifications` (optional).
      - Without a subscription: **1 free pricing request per calendar day** (soft-deleted requests still count for that day).
      - A second attempt the same day without an active AI subscription returns key `needSubscribe` (HTTP 400).
      - With an active AI package subscription (`POST /subscription`), pricing requests are unlimited.
      - AI engine is currently stubbed with a temporary random price; replace the stub in `PricingRequest.runAiPricingEngine` when the real AI API is connected.
      - The created row is saved into the pricing library.

      <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=9497-8155&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=10261-29943&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=9497-8155&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: "9497:8155"
      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=10261-29943&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10261:29943"
    operationId: createPricingRequest
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [name, image]
            properties:
              name:
                type: string
                minLength: 2
                maxLength: 200
                example: "آيفون 13"
              specifications:
                type: string
                maxLength: 2000
                example: "اللون أسود - الحالة جديد - الذاكرة 256"
              image:
                type: string
                format: binary
    responses:
      '200':
        description: Pricing completed (stub/random until AI is wired). Shape matches `returnObj.pricingRequestItem` (create view).
        content:
          application/json:
            schema:
              $ref: '../../openapi.yaml#/components/schemas/PricingRequestSuccessResponse'
            example:
              key: success
              message: "تم التسعير بنجاح"
              status: 200
              data:
                id: "665f1c2a9b4e1d0012ab34b1"
                name: "آيفون 13"
                image: "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/providers/pricing-requests/665f1c2a9b4e1d0012ab34b1/image901785232499932.png"
                specifications: "اللون أسود - الحالة جديد - الذاكرة 256"
                suggestedPrice: 450
                suggestedPriceTXT: "450 ﷼"
                priceRangeMin: 383
                priceRangeMax: 518
                currency: "﷼"
                createdAt: "2026/07/28 11:00 صباحا"
      '400':
        description: |
          Validation failure (`key: fail`) or daily free quota used (`key: needSubscribe`).
          Envelope is always `{ key, message, status }` with no `data`.
        content:
          application/json:
            schema: { $ref: '../../openapi.yaml#/components/schemas/ErrorResponse' }
            examples:
              needSubscribe:
                summary: Free daily quota already used (must subscribe)
                value:
                  key: needSubscribe
                  message: "تم استخدام التسعير المجاني لهذا اليوم. اشترك في باقة تسعير AI للمتابعة"
                  status: 400
              nameRequired:
                summary: Missing product name
                value:
                  key: fail
                  message: "اسم المنتج مطلوب يرجي ادخال البيانات"
                  status: 400
              nameLengthInvalid:
                summary: Name length invalid
                value:
                  key: fail
                  message: "اسم المنتج يجب أن يكون بين 2 و 200 حرف"
                  status: 400
              imageRequired:
                summary: Missing product image
                value:
                  key: fail
                  message: "صورة المنتج مطلوبة"
                  status: 400
              imageInvalidType:
                summary: Unsupported image type
                value:
                  key: fail
                  message: "صيغة صورة المنتج غير مدعومة"
                  status: 400
              specificationsTooLong:
                summary: Specifications too long
                value:
                  key: fail
                  message: "مواصفات المنتج طويلة جدًا"
                  status: 400
      '419':
        description: Bearer token missing/invalid (`auth.tokenRequired`).
        content:
          application/json:
            schema: { $ref: '../../openapi.yaml#/components/schemas/ErrorResponse' }
            example:
              key: unauthorized
              message: "مطلوب token"
              status: 419
      '500':
        description: Unexpected server error (`common.returnDeveloper`).
        content:
          application/json:
            schema: { $ref: '../../openapi.yaml#/components/schemas/ErrorResponse' }
            example:
              key: exception
              message: "حدث خطأ يرجي الرجوع للممبرمج"
              status: 500

shared-server-error:
  description: Unexpected server error.
  content:
    application/json:
      schema: { $ref: '../../openapi.yaml#/components/schemas/ErrorResponse' }
      example:
        key: exception
        message: "حدث خطأ يرجي الرجوع للممبرمج"
        status: 500
