openapi: 3.0.3
info:
  title: GiftKart API Documentation
  description: |-
    Production-grade API documentation for the GiftKart Ecommerce Platform.
    
    ### Access Levels:
    * **Public**: No authentication.
    * **Customer**: Requires Bearer Token (Sanctum).
    * **Admin**: Requires Bearer Token + Admin Role.
  version: 1.0.0
  contact:
    email: support@giftkart.com
servers:
  - url: http://localhost:8003/api/gk/v1
    description: Local Development Server

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    Product:
      type: object
      properties:
        uuid: { type: string, format: uuid }
        name: { type: string }
        slug: { type: string }
        base_price: { type: number }
        sale_price: { type: number, nullable: true }
        effective_price: { type: number }
        discount_percent: { type: integer, nullable: true }
        stock_status: { type: string, enum: [in_stock, out_of_stock, low_stock] }
        avg_rating: { type: number }
        review_count: { type: integer }
        image: { type: string, format: url }
        category: { type: string }

paths:
  /auth/register:
    post:
      tags: [Auth]
      summary: Register a new customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, email, password, password_confirmation]
              properties:
                name: { type: string }
                email: { type: string, format: email }
                phone: { type: string }
                password: { type: string, minLength: 8 }
                password_confirmation: { type: string }
      responses:
        201:
          description: Created
  
  /auth/login:
    post:
      tags: [Auth]
      summary: Login to account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email: { type: string, format: email }
                password: { type: string }
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      token: { type: string }
                      user: { type: object }

  /products:
    get:
      tags: [Products]
      summary: List all products
      parameters:
        - name: category_slug
          in: query
          schema: { type: string }
        - name: search
          in: query
          schema: { type: string }
        - name: min_price
          in: query
          schema: { type: number }
        - name: sort_by
          in: query
          schema: { type: string, enum: [created_at, sale_price, order_count, avg_rating] }
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Product' }

  /cart:
    get:
      security: [{ bearerAuth: [] }]
      tags: [Shopping Cart]
      summary: View current cart
      responses:
        200:
          description: OK
    post:
      security: [{ bearerAuth: [] }]
      tags: [Shopping Cart]
      summary: Add item to cart
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [product_id]
              properties:
                product_id: { type: integer }
                variant_id: { type: integer }
                quantity: { type: integer, default: 1 }
                gift_wrap: { type: boolean }
      responses:
        200:
          description: OK

  /pincodes/{pincode}/check:
    get:
      tags: [Logistics]
      summary: Check delivery availability
      parameters:
        - name: pincode
          in: path
          required: true
          schema: { type: string }
      responses:
        200:
          description: OK

  /checkout:
    post:
      security: [{ bearerAuth: [] }]
      tags: [Orders]
      summary: Place final order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shipping_name, shipping_phone, shipping_address, shipping_city, shipping_state, shipping_pincode, payment_method]
              properties:
                shipping_name: { type: string }
                shipping_phone: { type: string }
                shipping_address: { type: string }
                shipping_city: { type: string }
                shipping_state: { type: string }
                shipping_pincode: { type: string }
                payment_method: { type: string, enum: [cod, razorpay, stripe] }
      responses:
        201:
          description: Order Placed
