openapi: 3.0.0
info:
  title: E-commerce API
  description: REST API with Role-Based Access Control for E-commerce Platform
  version: 2.0.0
  contact:
    name: API Support
    email: support@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.verospace.app/api
    description: Rinaldi Api Production Server

tags:
  - name: Authentication
  - name: Users
  - name: Categories
  - name: Products
  - name: Variants
  - name: Cart
  - name: Transactions
  - name: Order Items
  - name: Data Stocks
  - name: News
  - name: Notifications
  - name: Settings
  - name: Reviews
  - name: Monitoring
  - name: Health

paths:
  /:
    get:
      tags: [Health]
      summary: API Health Check
      responses:
        '200':
          description: API is running

  /auth/register:
    post:
      tags: [Authentication]
      summary: Register user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthRegisterRequest'
      responses:
        '201':
          description: User registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthRegisterResponse'
        '409':
          description: Email/username already exists

  /auth/login:
    post:
      tags: [Authentication]
      summary: User login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthLoginRequest'
      responses:
        '200':
          description: Login success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthLoginResponse'
        '401':
          description: Invalid email or password
        '403':
          description: Account inactive

  /auth/logout:
    post:
      tags: [Authentication]
      summary: Logout user
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Logout success

  /auth/verify-email:
    post:
      tags: [Authentication]
      summary: Verify email
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Verified

  /auth/me:
    get:
      tags: [Authentication]
      summary: Get current user
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Current user

  /users/profile:
    get:
      tags: [Users]
      summary: Get user profile
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Profile retrieved
    put:
      tags: [Users]
      summary: Update user profile
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Profile updated

  /users/change-password:
    put:
      tags: [Users]
      summary: Change password
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Password updated

  /users:
    get:
      tags: [Users]
      summary: Get all users (admin)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Users retrieved

  /users/{id}:
    get:
      tags: [Users]
      summary: Get user by ID (admin)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: User retrieved
    delete:
      tags: [Users]
      summary: Delete user (admin)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: User deleted

  /users/{id}/role:
    put:
      tags: [Users]
      summary: Update user role (admin)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Role updated

  /users/{id}/status:
    put:
      tags: [Users]
      summary: Update user status (admin)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Status updated

  /users/{id}/balance:
    put:
      tags: [Users]
      summary: Update user balance (admin)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Balance updated

  /categories:
    get:
      tags: [Categories]
      summary: Get all categories
      responses:
        '200':
          description: Categories retrieved
    post:
      tags: [Categories]
      summary: Create category (admin/reseller)
      security:
        - bearerAuth: []
      responses:
        '201':
          description: Category created

  /categories/slug/{slug}:
    get:
      tags: [Categories]
      summary: Get category by slug
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Category retrieved

  /categories/{id}:
    get:
      tags: [Categories]
      summary: Get category by ID
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Category retrieved
    put:
      tags: [Categories]
      summary: Update category (admin/reseller)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Category updated
    delete:
      tags: [Categories]
      summary: Delete category (admin)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Category deleted

  /products:
    get:
      tags: [Products]
      summary: Get all products
      parameters:
        - name: category_id
          in: query
          schema: { type: integer }
        - name: status
          in: query
          schema: { type: integer }
        - name: search
          in: query
          schema: { type: string }
        - name: page
          in: query
          schema: { type: integer, default: 1 }
        - name: limit
          in: query
          schema: { type: integer, default: 10 }
        - name: sort
          in: query
          schema:
            type: string
            enum: [created_at, name, view, sold, sort]
        - name: order
          in: query
          schema:
            type: string
            enum: [ASC, DESC]
      responses:
        '200':
          description: Products retrieved
    post:
      tags: [Products]
      summary: Create product (admin/reseller)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductCreateRequest'
      responses:
        '201':
          description: Product created
        '404':
          description: Category not found
        '409':
          description: Product slug already exists

  /products/slug/{slug}:
    get:
      tags: [Products]
      summary: Get product by slug
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Product retrieved

  /products/{id}:
    get:
      tags: [Products]
      summary: Get product by ID
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Product retrieved
        '404':
          description: Product not found

  /variants/product/{product_id}:
    get:
      tags: [Variants]
      summary: Get variants by product
      parameters:
        - name: product_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Variants retrieved

  /variants/sku/{sku}:
    get:
      tags: [Variants]
      summary: Get variant by SKU
      parameters:
        - name: sku
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Variant retrieved

  /variants/{id}:
    get:
      tags: [Variants]
      summary: Get variant by ID
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Variant retrieved
    post:
      tags: [Variants]
      summary: Create variant (admin/reseller)
      security:
        - bearerAuth: []
      responses:
        '201':
          description: Variant created
    put:
      tags: [Variants]
      summary: Update variant (admin/reseller)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Variant updated
    delete:
      tags: [Variants]
      summary: Delete variant (admin)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Variant deleted

  /cart:
    get:
      tags: [Cart]
      summary: Get cart
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Cart retrieved
    post:
      tags: [Cart]
      summary: Add to cart
      security:
        - bearerAuth: []
      responses:
        '201':
          description: Added to cart
    delete:
      tags: [Cart]
      summary: Clear cart
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Cart cleared

  /cart/{id}:
    put:
      tags: [Cart]
      summary: Update cart item
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Cart item updated
    delete:
      tags: [Cart]
      summary: Delete cart item
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Cart item deleted

  /cart/toggle-check-all:
    post:
      tags: [Cart]
      summary: Toggle check all cart items
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Toggled

  /transactions:
    get:
      tags: [Transactions]
      summary: Get all transactions (admin)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Transactions retrieved

  /transactions/my-transactions:
    get:
      tags: [Transactions]
      summary: Get user transactions
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Transactions retrieved

  /transactions/checkout:
    post:
      tags: [Transactions]
      summary: Create transaction (checkout)
      security:
        - bearerAuth: []
      responses:
        '201':
          description: Transaction created

  /transactions/invoice/{invoice}:
    get:
      tags: [Transactions]
      summary: Get transaction by invoice
      security:
        - bearerAuth: []
      parameters:
        - name: invoice
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Transaction retrieved

  /transactions/{id}:
    get:
      tags: [Transactions]
      summary: Get transaction by ID
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Transaction retrieved

  /transactions/{id}/cancel:
    post:
      tags: [Transactions]
      summary: Cancel transaction
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Transaction canceled

  /transactions/{id}/status:
    put:
      tags: [Transactions]
      summary: Update transaction status (admin)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Status updated

  /order-items:
    get:
      tags: [Order Items]
      summary: Get all order items (admin)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Order items retrieved

  /order-items/my-orders:
    get:
      tags: [Order Items]
      summary: Get user order items
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Order items retrieved

  /order-items/{id}:
    get:
      tags: [Order Items]
      summary: Get order item by ID
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Order item retrieved

  /order-items/{id}/status:
    put:
      tags: [Order Items]
      summary: Update order item status (admin)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Status updated

  /data-stocks:
    get:
      tags: [Data Stocks]
      summary: Get data stocks
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Data stocks retrieved
    post:
      tags: [Data Stocks]
      summary: Create data stock
      security:
        - bearerAuth: []
      responses:
        '201':
          description: Data stock created

  /data-stocks/bulk:
    post:
      tags: [Data Stocks]
      summary: Bulk create data stocks
      security:
        - bearerAuth: []
      responses:
        '201':
          description: Data stocks created

  /data-stocks/variant/{variant_id}/count:
    get:
      tags: [Data Stocks]
      summary: Get stock count by variant
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Stock count retrieved

  /data-stocks/{id}:
    get:
      tags: [Data Stocks]
      summary: Get data stock by ID
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Data stock retrieved
    put:
      tags: [Data Stocks]
      summary: Update data stock
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Data stock updated
    delete:
      tags: [Data Stocks]
      summary: Delete data stock (admin)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Data stock deleted

  /news:
    get:
      tags: [News]
      summary: Get all news
      responses:
        '200':
          description: News retrieved
    post:
      tags: [News]
      summary: Create news (admin)
      security:
        - bearerAuth: []
      responses:
        '201':
          description: News created

  /news/slug/{slug}:
    get:
      tags: [News]
      summary: Get news by slug
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: News retrieved

  /news/{id}:
    get:
      tags: [News]
      summary: Get news by ID
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: News retrieved
    put:
      tags: [News]
      summary: Update news (admin)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: News updated
    delete:
      tags: [News]
      summary: Delete news (admin)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: News deleted

  /notifications:
    get:
      tags: [Notifications]
      summary: Get all notifications (admin)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Notifications retrieved
    post:
      tags: [Notifications]
      summary: Create notification (admin)
      security:
        - bearerAuth: []
      responses:
        '201':
          description: Notification created

  /notifications/broadcast:
    post:
      tags: [Notifications]
      summary: Broadcast notification (admin)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Broadcast sent

  /notifications/my-notifications:
    get:
      tags: [Notifications]
      summary: Get user notifications
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Notifications retrieved

  /notifications/clear-all:
    delete:
      tags: [Notifications]
      summary: Clear all user notifications
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Notifications cleared

  /notifications/{id}:
    get:
      tags: [Notifications]
      summary: Get notification by ID
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Notification retrieved
    delete:
      tags: [Notifications]
      summary: Delete notification
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Notification deleted

  /settings:
    get:
      tags: [Settings]
      summary: Get settings
      responses:
        '200':
          description: Settings retrieved
    put:
      tags: [Settings]
      summary: Update settings (admin)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Settings updated

  /reviews:
    post:
      tags: [Reviews]
      summary: Create review for a transaction
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewCreateRequest'
      responses:
        '201':
          description: Review created
        '400':
          description: Invalid rating / transaction not completed
        '403':
          description: Not your transaction
        '404':
          description: Transaction not found
        '409':
          description: Review already exists

  /reviews/transaction/{transaction_id}:
    get:
      tags: [Reviews]
      summary: Get reviews by transaction
      security:
        - bearerAuth: []
      parameters:
        - name: transaction_id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Reviews retrieved
        '400':
          description: Invalid transaction ID

  /reviews/{id}:
    get:
      tags: [Reviews]
      summary: Get review by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Review retrieved
        '404':
          description: Review not found

  /monitoring/resources:
    get:
      tags: [Monitoring]
      summary: Get server resource usage
      responses:
        '200':
          description: Resource usage retrieved

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token with no expiration

  schemas:
    AuthRegisterRequest:
      type: object
      required: [name, username, email, password]
      properties:
        name: { type: string }
        username: { type: string }
        email: { type: string, format: email }
        password: { type: string, format: password, minLength: 6 }
        role:
          type: string
          enum: [user, admin, reseller]
          default: user
        phone: { type: string, nullable: true }

    AuthRegisterResponse:
      type: object
      properties:
        success: { type: boolean, example: true }
        message: { type: string, example: User registered successfully }
        data:
          type: object
          properties:
            id: { type: integer }
            name: { type: string }
            username: { type: string }
            email: { type: string, format: email }
            role: { type: string }
            phone: { type: string, nullable: true }
            balance: { type: integer, example: 0 }
            status: { type: string, example: active }

    AuthLoginRequest:
      type: object
      required: [email, password]
      properties:
        email: { type: string, format: email }
        password: { type: string, format: password }

    AuthLoginResponse:
      type: object
      properties:
        success: { type: boolean, example: true }
        message: { type: string, example: Login successful }
        data:
          type: object
          properties:
            token: { type: string }
            user:
              type: object
              properties:
                id: { type: integer }
                name: { type: string }
                username: { type: string }
                email: { type: string, format: email }
                role: { type: string }
                phone: { type: string, nullable: true }
                balance: { type: integer }
                status: { type: string }
                email_verified_at: { type: string, nullable: true }

    ProductCreateRequest:
      type: object
      required: [category_id, name, slug]
      properties:
        sort: { type: integer, default: 0 }
        category_id: { type: integer }
        name: { type: string }
        slug: { type: string }
        image: { type: string, nullable: true }
        description: { type: string, nullable: true }
        status: { type: integer, default: 1 }

    ReviewCreateRequest:
      type: object
      required: [transaction_id, rating]
      properties:
        transaction_id: { type: integer }
        rating:
          type: integer
          enum: [1, 2, 3, 4, 5]
        review: { type: string, nullable: true }

security:
  - bearerAuth: []
