openapi: 3.0.3
info:
  title: My Site Backend Email API
  version: 1.0.0
  description: API contract for the contact form backend endpoint implemented in `contact.php`.

servers:
  - url: /
    description: Same host

paths:
  /contact.php:
    options:
      tags: [Contact]
      summary: CORS preflight
      responses:
        '204':
          description: No content
    post:
      tags: [Contact]
      summary: Submit contact form and trigger emails
      description: |
        Accepts either `application/json` or form-encoded payloads.
        On success, sends owner notification + user confirmation email.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactSubmitRequest'
            examples:
              basic:
                value:
                  name: Jane Doe
                  email: jane@example.com
                  company: Acme Inc
                  timeline: Q3 2026
                  projectType: Website redesign
                  message: Need a modern website with CMS.
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ContactSubmitRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ContactSubmitRequest'
      responses:
        '200':
          description: Contact request accepted and emails sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactSubmitSuccessResponse'
              examples:
                success:
                  value:
                    success: true
                    data:
                      success: true
                      message: Contact request submitted successfully.
        '400':
          description: Invalid JSON or empty payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidJson:
                  value:
                    success: false
                    error:
                      code: INVALID_JSON
                      message: Request body contains invalid JSON.
                      details:
                        jsonError: Syntax error
                emptyPayload:
                  value:
                    success: false
                    error:
                      code: EMPTY_PAYLOAD
                      message: Request payload is empty. Send JSON or form fields.
        '405':
          description: HTTP method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                methodNotAllowed:
                  value:
                    success: false
                    error:
                      code: METHOD_NOT_ALLOWED
                      message: Method not allowed. Use POST.
                      details:
                        allowedMethods:
                          - POST
                          - OPTIONS
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingFields:
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Missing required fields.
                invalidEmail:
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid email address.
        '500':
          description: Server or email delivery error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                emailConfigError:
                  value:
                    success: false
                    error:
                      code: EMAIL_CONFIG_ERROR
                      message: Email service is not configured correctly.
                templateError:
                  value:
                    success: false
                    error:
                      code: EMAIL_TEMPLATE_NOT_FOUND
                      message: Email template configuration error.
                sendError:
                  value:
                    success: false
                    error:
                      code: EMAIL_SEND_FAILED
                      message: Failed to send email.
                internalError:
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: Failed to submit contact form.

components:
  schemas:
    ContactSubmitRequest:
      type: object
      required:
        - name
        - email
        - projectType
        - message
      properties:
        name:
          type: string
          minLength: 1
          example: Jane Doe
        email:
          type: string
          format: email
          minLength: 3
          example: jane@example.com
        company:
          type: string
          example: Acme Inc
          default: ''
        timeline:
          type: string
          example: Q3 2026
          default: ''
        projectType:
          type: string
          minLength: 1
          example: Website redesign
        message:
          type: string
          minLength: 1
          example: Need a modern website with CMS.
      additionalProperties: true

    ContactSubmitSuccessResponse:
      type: object
      required: [success, data]
      properties:
        success:
          type: boolean
          enum: [true]
        data:
          type: object
          required: [success, message]
          properties:
            success:
              type: boolean
              enum: [true]
            message:
              type: string
              example: Contact request submitted successfully.
          additionalProperties: true
      additionalProperties: false

    ErrorResponse:
      type: object
      required: [success, error]
      properties:
        success:
          type: boolean
          enum: [false]
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              enum:
                - METHOD_NOT_ALLOWED
                - INVALID_JSON
                - EMPTY_PAYLOAD
                - VALIDATION_ERROR
                - EMAIL_CONFIG_ERROR
                - EMAIL_TEMPLATE_NOT_FOUND
                - EMAIL_SEND_FAILED
                - INTERNAL_ERROR
              example: VALIDATION_ERROR
            message:
              type: string
              example: Missing required fields.
            details:
              type: object
              additionalProperties: true
              description: Optional machine-readable details (for example allowed methods or JSON parser message).
            debug:
              $ref: '#/components/schemas/ErrorDebug'
          additionalProperties: false
      additionalProperties: false

    ErrorDebug:
      type: object
      description: Present only when debug mode is enabled (`APP_ENV=dev` or `APP_DEBUG=true`).
      required: [type, message, file, line]
      properties:
        type:
          type: string
          example: RuntimeException
        message:
          type: string
        file:
          type: string
        line:
          type: integer
          example: 42
      additionalProperties: false
