
openapi: 3.0.3
info:
  title: Electe API
  description: |
    API completa per la gestione di progetti e utenti con sistema di webhook real-time.
    
    ## Autenticazione
    L'API utilizza JWT Bearer tokens per l'autenticazione. Ottenere un token tramite l'endpoint `/auth` con action "login".
    
    ## Rate Limiting
    - 1000 richieste/ora per utente autenticato
    - 100 richieste/ora per IP (non autenticato)
    
    ## Webhook
    Supporta webhook real-time per notificare eventi. Eventi disponibili:
    - `user.created` - Nuovo utente registrato
    - `project.created` - Nuovo progetto creato
    - `project.updated` - Progetto aggiornato
    - `project.deleted` - Progetto eliminato
    
  version: 1.0.0
  contact:
    name: Electe API Support
    url: https://api.electe.net
    email: support@electe.net

servers:
  - url: https://api.electe.net/.netlify/functions
    description: Production server

security:
  - BearerAuth: []

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

paths:
  /auth:
    post:
      summary: Autenticazione utenti
      description: Login e registrazione utenti
      tags: [Authentication]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    action:
                      type: string
                      enum: [login]
                    email:
                      type: string
                      format: email
                    password:
                      type: string
                - type: object
                  properties:
                    action:
                      type: string
                      enum: [signup]
                    email:
                      type: string
                      format: email
                    password:
                      type: string
                    fullName:
                      type: string
      responses:
        '200':
          description: Success
        '201':
          description: Created

  /projects:
    get:
      summary: Lista progetti
      tags: [Projects]
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
            maximum: 100
      responses:
        '200':
          description: Lista progetti
    post:
      summary: Crea progetto
      tags: [Projects]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  maxLength: 100
                description:
                  type: string
                  maxLength: 500
      responses:
        '201':
          description: Progetto creato

  /webhooks:
    get:
      summary: Lista webhook
      tags: [Webhooks]
      responses:
        '200':
          description: Lista webhook
    post:
      summary: Registra webhook
      tags: [Webhooks]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url, events]
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  items:
                    type: string
                    enum: [user.created, project.created, project.updated, project.deleted]
      responses:
        '201':
          description: Webhook registrato

tags:
  - name: Authentication
    description: Operazioni di autenticazione
  - name: Projects
    description: Gestione progetti
  - name: Webhooks
    description: Sistema notifiche real-time
