openapi.yaml

openapi: 3.1.0
info:
  title: Clicky-Store API
  version: 0.1.0
  description: REST API for the Clicky-Store educational e-commerce project.
servers:
  - url: http://localhost:8080/api/v1
paths:
  /auth/register:
    post:
      summary: Register a customer account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterRequest"
      responses:
        "201":
          description: Registered user and bearer token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthResponse"
        "400":
          $ref: "#/components/responses/Error"
        "409":
          $ref: "#/components/responses/Error"
  /auth/login:
    post:
      summary: Login with email and password
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequest"
      responses:
        "200":
          description: Logged-in user and bearer token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthResponse"
        "401":
          $ref: "#/components/responses/Error"
        "429":
          $ref: "#/components/responses/Error"
  /me:
    get:
      summary: Get the authenticated user
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Current user
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Error"
  /products:
    get:
      summary: List public products
      parameters:
        - in: query
          name: category
          schema:
            type: string
        - in: query
          name: q
          schema:
            type: string
      responses:
        "200":
          description: Product list
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: array
                    items:
                      $ref: "#/components/schemas/Product"
  /products/{productId}:
    get:
      summary: Get a public product
      parameters:
        - $ref: "#/components/parameters/ProductId"
      responses:
        "200":
          description: Product detail
          content:
            application/json:
              schema:
                type: object
                properties:
                  product:
                    $ref: "#/components/schemas/Product"
        "404":
          $ref: "#/components/responses/Error"
  /products/slug/{slug}:
    get:
      summary: Get a public product by slug
      parameters:
        - $ref: "#/components/parameters/ProductSlug"
      responses:
        "200":
          description: Product detail
          content:
            application/json:
              schema:
                type: object
                properties:
                  product:
                    $ref: "#/components/schemas/Product"
        "404":
          $ref: "#/components/responses/Error"
  /cart:
    get:
      summary: Get the authenticated user's cart
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Cart
          content:
            application/json:
              schema:
                type: object
                properties:
                  cart:
                    $ref: "#/components/schemas/Cart"
        "401":
          $ref: "#/components/responses/Error"
  /cart/items:
    post:
      summary: Add an item to the authenticated user's cart
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CartItemRequest"
      responses:
        "201":
          description: Updated cart
          content:
            application/json:
              schema:
                type: object
                properties:
                  cart:
                    $ref: "#/components/schemas/Cart"
        "400":
          $ref: "#/components/responses/Error"
        "409":
          $ref: "#/components/responses/Error"
  /cart/items/{productId}:
    patch:
      summary: Set a cart item quantity
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProductId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - quantity
              properties:
                quantity:
                  type: integer
                  minimum: 0
      responses:
        "200":
          $ref: "#/components/responses/Cart"
        "400":
          $ref: "#/components/responses/Error"
        "409":
          $ref: "#/components/responses/Error"
    delete:
      summary: Remove a cart item
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProductId"
      responses:
        "200":
          $ref: "#/components/responses/Cart"
        "404":
          $ref: "#/components/responses/Error"
  /orders:
    get:
      summary: List the authenticated user's orders
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/Orders"
    post:
      summary: Create an order from the authenticated user's cart
      description: Creates a pending simulated payment, decreases stock, snapshots order items, and clears the cart transactionally.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                paymentMethod:
                  type: string
                  example: simulation
      responses:
        "201":
          $ref: "#/components/responses/Order"
        "400":
          $ref: "#/components/responses/Error"
        "409":
          $ref: "#/components/responses/Error"
  /orders/{orderId}/payment/simulate:
    post:
      summary: Simulate payment for a pending order
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrderId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - result
              properties:
                result:
                  type: string
                  enum:
                    - success
                    - failure
      responses:
        "200":
          $ref: "#/components/responses/Order"
        "400":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /admin/products:
    get:
      summary: List products as admin
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/Products"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
    post:
      summary: Create a product as admin
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProductRequest"
      responses:
        "201":
          $ref: "#/components/responses/Product"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "409":
          $ref: "#/components/responses/Error"
  /admin/products/{productId}:
    patch:
      summary: Update a product as admin
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProductId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProductUpdateRequest"
      responses:
        "200":
          $ref: "#/components/responses/Product"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "409":
          $ref: "#/components/responses/Error"
    delete:
      summary: Delete a product as admin
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProductId"
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /admin/products/{productId}/images:
    post:
      summary: Upload product images as admin
      description: Accepts JPEG and PNG files in the `images` multipart field. A product can have at most 10 total images.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProductId"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - images
              properties:
                images:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        "201":
          $ref: "#/components/responses/ProductImages"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /admin/products/{productId}/images/order:
    patch:
      summary: Reorder product images as admin
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProductId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - imageIds
              properties:
                imageIds:
                  type: array
                  items:
                    type: string
      responses:
        "200":
          $ref: "#/components/responses/ProductImages"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /admin/products/{productId}/images/{imageId}:
    patch:
      summary: Update product image metadata or primary status as admin
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProductId"
        - $ref: "#/components/parameters/ImageId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProductImageUpdateRequest"
      responses:
        "200":
          description: Updated product image
          content:
            application/json:
              schema:
                type: object
                properties:
                  image:
                    $ref: "#/components/schemas/ProductImage"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    delete:
      summary: Delete product image metadata as admin
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ProductId"
        - $ref: "#/components/parameters/ImageId"
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /admin/orders:
    get:
      summary: List all orders as admin
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/Orders"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
  /admin/users:
    get:
      summary: List users as admin
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: role
          schema:
            type: string
            enum:
              - admin
              - customer
        - in: query
          name: q
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/Users"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
  /admin/users/{userId}:
    get:
      summary: Get a user as admin
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "200":
          $ref: "#/components/responses/User"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    patch:
      summary: Update a user role as admin
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/UserId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - role
              properties:
                role:
                  type: string
                  enum:
                    - admin
                    - customer
      responses:
        "200":
          $ref: "#/components/responses/User"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  parameters:
    ProductId:
      in: path
      name: productId
      required: true
      schema:
        type: string
    ProductSlug:
      in: path
      name: slug
      required: true
      schema:
        type: string
    ImageId:
      in: path
      name: imageId
      required: true
      schema:
        type: string
    OrderId:
      in: path
      name: orderId
      required: true
      schema:
        type: string
    UserId:
      in: path
      name: userId
      required: true
      schema:
        type: string
  responses:
    Error:
      description: JSON error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Cart:
      description: Updated cart
      content:
        application/json:
          schema:
            type: object
            properties:
              cart:
                $ref: "#/components/schemas/Cart"
    Order:
      description: Order
      content:
        application/json:
          schema:
            type: object
            properties:
              order:
                $ref: "#/components/schemas/Order"
    Orders:
      description: Order list
      content:
        application/json:
          schema:
            type: object
            properties:
              orders:
                type: array
                items:
                  $ref: "#/components/schemas/Order"
    Product:
      description: Product
      content:
        application/json:
          schema:
            type: object
            properties:
              product:
                $ref: "#/components/schemas/Product"
    Products:
      description: Product list
      content:
        application/json:
          schema:
            type: object
            properties:
              products:
                type: array
                items:
                  $ref: "#/components/schemas/Product"
    ProductImages:
      description: Product images
      content:
        application/json:
          schema:
            type: object
            properties:
              images:
                type: array
                items:
                  $ref: "#/components/schemas/ProductImage"
    User:
      description: User
      content:
        application/json:
          schema:
            type: object
            properties:
              user:
                $ref: "#/components/schemas/User"
    Users:
      description: User list
      content:
        application/json:
          schema:
            type: object
            properties:
              users:
                type: array
                items:
                  $ref: "#/components/schemas/User"
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    RegisterRequest:
      type: object
      required:
        - name
        - email
        - password
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8
    LoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
        password:
          type: string
    AuthResponse:
      type: object
      properties:
        user:
          $ref: "#/components/schemas/User"
        token:
          type: string
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
        role:
          type: string
          enum:
            - admin
            - customer
        createdAt:
          type: string
          format: date-time
    ProductRequest:
      type: object
      required:
        - name
        - slug
        - description
        - category
        - priceCents
        - currency
        - dpi
        - stock
      properties:
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        category:
          type: string
        priceCents:
          type: integer
          minimum: 1
        currency:
          type: string
          example: PLN
        dpi:
          type: integer
          minimum: 1
        wireless:
          type: boolean
        ergonomic:
          type: boolean
        stock:
          type: integer
          minimum: 0
        imageUrl:
          type: string
    ProductUpdateRequest:
      type: object
      description: Partial product update. Omitted fields are left unchanged.
      properties:
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        category:
          type: string
        priceCents:
          type: integer
          minimum: 1
        currency:
          type: string
          example: PLN
        dpi:
          type: integer
          minimum: 1
        wireless:
          type: boolean
        ergonomic:
          type: boolean
        stock:
          type: integer
          minimum: 0
        imageUrl:
          type: string
    Product:
      allOf:
        - $ref: "#/components/schemas/ProductRequest"
        - type: object
          properties:
            id:
              type: string
            images:
              type: array
              items:
                $ref: "#/components/schemas/ProductImage"
            createdAt:
              type: string
              format: date-time
            updatedAt:
              type: string
              format: date-time
    ProductImage:
      type: object
      properties:
        id:
          type: string
        productId:
          type: string
        url:
          type: string
          example: /assets/products/viper-x1.svg
        altText:
          type: string
        sortOrder:
          type: integer
          minimum: 0
        isPrimary:
          type: boolean
        createdAt:
          type: string
          format: date-time
    ProductImageUpdateRequest:
      type: object
      properties:
        altText:
          type: string
        sortOrder:
          type: integer
          minimum: 0
        isPrimary:
          type: boolean
    CartItemRequest:
      type: object
      required:
        - productId
        - quantity
      properties:
        productId:
          type: string
        quantity:
          type: integer
          minimum: 1
    Cart:
      type: object
      properties:
        userId:
          type: string
        items:
          type: array
          items:
            $ref: "#/components/schemas/CartLine"
        totalCents:
          type: integer
        currency:
          type: string
    CartLine:
      type: object
      properties:
        product:
          $ref: "#/components/schemas/Product"
        quantity:
          type: integer
        subtotalCents:
          type: integer
    Order:
      type: object
      properties:
        id:
          type: string
        userId:
          type: string
        items:
          type: array
          items:
            $ref: "#/components/schemas/OrderItem"
        totalCents:
          type: integer
        currency:
          type: string
        status:
          type: string
          enum:
            - pending
            - confirmed
            - payment_failed
        paymentStatus:
          type: string
          enum:
            - pending
            - paid
            - failed
        paymentMethod:
          type: string
        createdAt:
          type: string
          format: date-time
    OrderItem:
      type: object
      properties:
        productId:
          type: string
        name:
          type: string
        quantity:
          type: integer
        unitPriceCents:
          type: integer
        subtotalCents:
          type: integer