openapi: 3.1.0
info:
  title: Spiked Website Backend API
  version: 0.1.0
  description: OpenAPI spec for the SpikedAI backend, including the streaming chatbot route, email storage APIs, and training-data inspection endpoints.
servers:
  - url: http://localhost:8080
    description: Local development server
tags:
  - name: Health
  - name: Chatbot
  - name: Email
  - name: RAG
paths:
  /health:
    get:
      tags: [Health]
      summary: Health check
      responses:
        "200":
          description: Service is running
          content:
            application/json:
              schema:
                type: object
                required: [ok, service]
                properties:
                  ok:
                    type: boolean
                    example: true
                  service:
                    type: string
                    example: spiked-website-backend
  /api/chatbot/stream:
    post:
      tags: [Chatbot]
      summary: Stream chatbot response over Server-Sent Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message]
              properties:
                message:
                  type: string
                  description: Current user message
                history:
                  type: array
                  description: Optional conversation history
                  items:
                    type: object
                    additionalProperties: true
                visitorContext:
                  type: object
                  description: Optional visitor metadata used for personalization
                  additionalProperties: true
                emailAddress:
                  type: string
                  format: email
                  description: Preferred email address for contact-sales flows
      responses:
        "200":
          description: SSE stream
          content:
            text/event-stream:
              schema:
                type: string
              examples:
                status:
                  summary: Status event
                  value: 'data: {"type":"status","message":"Processing your request..."}'
                response:
                  summary: Final response event
                  value: 'data: {"type":"response","data":{"response":"...","suggestions":null,"intent":null,"inbound_preview":null,"email_result":null,"modal_error":null}}'
        "400":
          description: Invalid chatbot request
          content:
            text/event-stream:
              schema:
                type: string
                examples:
                  missingMessage:
                    value: 'data: {"type":"error","error":"Message is required and must be a string"}'
  /api/email/send:
    post:
      tags: [Email]
      summary: Send an email and store the sent record
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [to, subject]
              properties:
                to:
                  type: string
                  format: email
                subject:
                  type: string
                body:
                  type: string
                text:
                  type: string
                html:
                  type: string
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        "200":
          description: Email stored and optionally delivered
          content:
            application/json:
              schema:
                type: object
                required: [success, provider, record]
                properties:
                  success:
                    type: boolean
                    example: true
                  provider:
                    type: string
                    enum: [storage, resend]
                  messageId:
                    type: [string, "null"]
                  record:
                    $ref: "#/components/schemas/SentEmailRecord"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Email send failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/email/receive:
    post:
      tags: [Email]
      summary: Store a received email record
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [from, subject]
              properties:
                from:
                  type: string
                  format: email
                to:
                  type: string
                  format: email
                subject:
                  type: string
                text:
                  type: string
                html:
                  type: string
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        "200":
          description: Email stored
          content:
            application/json:
              schema:
                type: object
                required: [success, record]
                properties:
                  success:
                    type: boolean
                    example: true
                  record:
                    $ref: "#/components/schemas/ReceivedEmailRecord"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Email receive failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/email/inbox:
    get:
      tags: [Email]
      summary: List received emails
      responses:
        "200":
          description: Inbox records
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/ReceivedEmailRecord"
  /api/email/sent:
    get:
      tags: [Email]
      summary: List sent emails
      responses:
        "200":
          description: Sent records
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/SentEmailRecord"
  /api/email/inbox/view:
    get:
      tags: [Email]
      summary: HTML inbox view
      responses:
        "200":
          description: HTML inbox page
          content:
            text/html:
              schema:
                type: string
        "500":
          description: Failed to render inbox view
          content:
            text/plain:
              schema:
                type: string
  /api/rag/training-files:
    get:
      tags: [RAG]
      summary: List available training files in the inbox corpus
      responses:
        "200":
          description: Training files
          content:
            application/json:
              schema:
                type: object
                required: [files]
                properties:
                  files:
                    type: array
                    items:
                      type: object
                      required: [folder, name]
                      properties:
                        folder:
                          type: string
                          example: inbox
                        name:
                          type: string
                          example: about-us.txt
components:
  schemas:
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
    SentEmailRecord:
      type: object
      required: [id, type, to, subject, text, html, metadata, provider, createdAt]
      properties:
        id:
          type: string
        type:
          type: string
          example: sent
        to:
          type: string
          format: email
        subject:
          type: string
        text:
          type: string
        html:
          type: string
        metadata:
          type: object
          additionalProperties: true
        provider:
          type: string
          enum: [storage, resend]
        providerMessageId:
          type: [string, "null"]
        createdAt:
          type: string
          format: date-time
    ReceivedEmailRecord:
      type: object
      required: [id, type, from, to, subject, text, html, metadata, createdAt]
      properties:
        id:
          type: string
        type:
          type: string
          example: received
        from:
          type: string
          format: email
        to:
          type: string
          format: email
        subject:
          type: string
        text:
          type: string
        html:
          type: string
        metadata:
          type: object
          additionalProperties: true
        createdAt:
          type: string
          format: date-time