openapi: 3.1.0
info:
  title: MODAVA API
  description: Fashion SaaS platform API for vendors and customers
  version: 1.0.0
  contact:
    name: MODAVA Support
    email: support@modava.com

servers:
  - url: https://api.modava.com
    description: Production server
  - url: http://localhost:3000
    description: Development server

paths:
  /health:
    get:
      summary: Health check
      responses:
        '200':
          description: System health status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "OK"
                  timestamp:
                    type: string
                    format: date-time
                  environment:
                    type: string
                    example: "production"

  /api/auth/signup:
    post:
      summary: Register new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  minLength: 6
                business_name:
                  type: string
                  maxLength: 100
      responses:
        '201':
          description: User registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '400':
          description: Validation error
        '409':
          description: User already exists

  /api/auth/login:
    post:
      summary: User login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          description: Invalid credentials

  /api/auth/profile:
    get:
      summary: Get user profile
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Profile retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      user:
                        $ref: '#/components/schemas/User'
                      vendor:
                        $ref: '#/components/schemas/Vendor'
        '401':
          description: Authentication required

  /api/vendors/me:
    get:
      summary: Get current vendor profile
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Vendor profile retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Vendor'

  /api/vendors/onboarding:
    post:
      summary: Complete vendor onboarding
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - business_name
              properties:
                business_name:
                  type: string
                  minLength: 2
                  maxLength: 100
                profile_picture_url:
                  type: string
                  format: uri
      responses:
        '200':
          description: Onboarding completed
        '400':
          description: Validation error

  /api/customers:
    get:
      summary: List customers
      security:
        - BearerAuth: []
      parameters:
        - name: search
          in: query
          schema:
            type: string
        - name: tag
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Customers retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
        '403':
          description: Feature not available

    post:
      summary: Create customer
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerCreate'
      responses:
        '201':
          description: Customer created
        '403':
          description: Feature not available

  /api/customers/{customerId}:
    get:
      summary: Get customer profile
      security:
        - BearerAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Customer profile retrieved
        '404':
          description: Customer not found

    put:
      summary: Update customer
      security:
        - BearerAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerUpdate'
      responses:
        '200':
          description: Customer updated

  /api/customers/{customerId}/measurements:
    post:
      summary: Update customer measurements
      security:
        - BearerAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Measurement'
      responses:
        '200':
          description: Measurements updated

  /api/invoices:
    get:
      summary: List invoices
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Invoices retrieved
        '403':
          description: Feature not available

    post:
      summary: Create invoice
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceCreate'
      responses:
        '201':
          description: Invoice created

  /api/invoices/{id}:
    get:
      summary: Get invoice details
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Invoice retrieved

    delete:
      summary: Delete invoice
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Invoice deleted

  /api/invoices/view/{public_code}:
    get:
      summary: View public invoice
      parameters:
        - name: public_code
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Invoice retrieved

  /api/reminders/create:
    post:
      summary: Create reminder
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReminderCreate'
      responses:
        '200':
          description: Reminder created
        '403':
          description: Feature not available

  /api/reminders/list:
    get:
      summary: List reminders
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Reminders retrieved
        '403':
          description: Feature not available

  /api/subscriptions/plans:
    get:
      summary: Get subscription plans
      responses:
        '200':
          description: Plans retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Plan'

  /api/subscriptions/my-plan:
    get:
      summary: Get current subscription
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Subscription retrieved

  /api/kyc/submit:
    post:
      summary: Submit KYC documents
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KYCSubmit'
      responses:
        '200':
          description: KYC submitted

  /api/kyc/status:
    get:
      summary: Get KYC status
      security:
        - BearerAuth: []
      responses:
        '200':
          description: KYC status retrieved

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

  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        user_metadata:
          type: object
          properties:
            role:
              type: string
              enum: [vendor, admin, staff, superadmin]
        created_at:
          type: string
          format: date-time

    Vendor:
      type: object
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        business_name:
          type: string
        email:
          type: string
          format: email
        onboarding_status:
          type: string
          enum: [incomplete, complete]
        subscription_plan:
          type: string
        created_at:
          type: string
          format: date-time

    Customer:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        phone:
          type: string
        email:
          type: string
          format: email
        notes:
          type: string
        is_flagged:
          type: boolean
        created_at:
          type: string
          format: date-time

    CustomerCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        phone:
          type: string
        email:
          type: string
          format: email
        notes:
          type: string

    CustomerUpdate:
      type: object
      properties:
        name:
          type: string
        phone:
          type: string
        email:
          type: string
          format: email
        notes:
          type: string

    Measurement:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
        unit:
          type: string

    Invoice:
      type: object
      properties:
        id:
          type: string
          format: uuid
        customer_id:
          type: string
          format: uuid
        total_amount:
          type: number
        status:
          type: string
          enum: [draft, sent, paid, overdue, cancelled]
        created_at:
          type: string
          format: date-time

    InvoiceCreate:
      type: object
      required:
        - customer_id
        - items
      properties:
        customer_id:
          type: string
          format: uuid
        items:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              quantity:
                type: number
              unit_price:
                type: number

    Reminder:
      type: object
      properties:
        id:
          type: string
          format: uuid
        customer_id:
          type: string
          format: uuid
        message:
          type: string
        type:
          type: string
        status:
          type: string
          enum: [draft, scheduled, sent, cancelled]
        scheduled_at:
          type: string
          format: date-time

    ReminderCreate:
      type: object
      required:
        - customer_id
        - message
      properties:
        customer_id:
          type: string
          format: uuid
        message:
          type: string
        type:
          type: string
        scheduled_at:
          type: string
          format: date-time

    Plan:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        price:
          type: number
        trial_period_days:
          type: integer

    KYCSubmit:
      type: object
      required:
        - document_urls
      properties:
        document_urls:
          type: object
          additionalProperties:
            type: string
            format: uri

    AuthResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            user:
              $ref: '#/components/schemas/User'
            vendor:
              $ref: '#/components/schemas/Vendor'
            access_token:
              type: string
            refresh_token:
              type: string
        message:
          type: string

tags:
  - name: Authentication
    description: User authentication and management
  - name: Vendors
    description: Vendor profile management
  - name: Customers
    description: Customer management
  - name: Invoices
    description: Invoice management
  - name: Reminders
    description: Customer reminder system
  - name: Subscriptions
    description: Subscription plan management
  - name: KYC
    description: Know Your Customer verification
