{
  "openapi": "3.1.0",
  "info": {
    "title": "Feriados CR",
    "version": "1.1.0",
    "description": "API pública con los feriados de Costa Rica según el Código de Trabajo y el calendario del MTSS. Sin registro ni clave, con CORS habilitado. Años disponibles: 2025 a 2100. Las fechas usan la hora de Costa Rica (UTC-6).",
    "contact": {
      "name": "Santiago Sánchez",
      "url": "https://santiagosanchez.dev"
    }
  },
  "servers": [
    {
      "url": "https://feriados.santiagosanchez.dev"
    }
  ],
  "paths": {
    "/api/v1/{year}": {
      "get": {
        "summary": "Feriados de un año",
        "parameters": [
          {
            "name": "year",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 2025,
              "maximum": 2100
            },
            "example": 2026
          },
          {
            "name": "pago",
            "in": "query",
            "required": false,
            "description": "Filtra por tipo de pago",
            "schema": {
              "type": "string",
              "enum": [
                "obligatorio",
                "no-obligatorio"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de feriados ordenada por fecha",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/YearResponse"
                }
              }
            }
          },
          "400": {
            "description": "Año fuera de rango (2025–2100) o filtro de pago inválido",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/{year}.ics": {
      "get": {
        "summary": "Calendario iCalendar del año",
        "description": "Para importar en Google Calendar, Outlook o Apple Calendar. Acepta el mismo filtro `pago`.",
        "parameters": [
          {
            "name": "year",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 2025,
              "maximum": 2100
            },
            "example": 2026
          },
          {
            "name": "pago",
            "in": "query",
            "required": false,
            "description": "Filtra por tipo de pago",
            "schema": {
              "type": "string",
              "enum": [
                "obligatorio",
                "no-obligatorio"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Archivo .ics",
            "content": {
              "text/calendar": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Año fuera de rango o filtro de pago inválido",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/proximo": {
      "get": {
        "summary": "Próximo feriado",
        "description": "Desde hoy (incluido), con los días que faltan.",
        "responses": {
          "200": {
            "description": "El próximo feriado",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Holiday"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "days_until": {
                          "type": "integer",
                          "minimum": 0,
                          "example": 36
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/hoy": {
      "get": {
        "summary": "¿Hoy es feriado?",
        "responses": {
          "200": {
            "description": "Resultado para hoy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DateResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/fecha/{date}": {
      "get": {
        "summary": "¿Una fecha es feriado?",
        "parameters": [
          {
            "name": "date",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-12-25"
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado para la fecha",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Fecha inexistente (por ejemplo 2026-02-30) o año fuera de rango",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Formato de fecha distinto de AAAA-MM-DD",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Estado del servicio",
        "responses": {
          "200": {
            "description": "El servicio está funcionando",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "version": {
                      "type": "string",
                      "example": "1.1.0"
                    },
                    "time": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Holiday": {
        "type": "object",
        "required": [
          "date",
          "name",
          "name_en",
          "mandatory_pay",
          "weekday",
          "weekday_en"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "description": "Fecha en que se disfruta el feriado",
            "example": "2026-09-15"
          },
          "legal_date": {
            "type": "string",
            "format": "date",
            "description": "Solo aparece si una ley trasladó el feriado a otra fecha"
          },
          "name": {
            "type": "string",
            "example": "Día de la Independencia"
          },
          "name_en": {
            "type": "string",
            "example": "Independence Day"
          },
          "mandatory_pay": {
            "type": "boolean",
            "description": "true si es de pago obligatorio (Código de Trabajo, art. 148)"
          },
          "weekday": {
            "type": "string",
            "example": "martes"
          },
          "weekday_en": {
            "type": "string",
            "example": "Tuesday"
          }
        }
      },
      "YearResponse": {
        "type": "object",
        "properties": {
          "year": {
            "type": "integer",
            "example": 2026
          },
          "country": {
            "type": "string",
            "example": "CR"
          },
          "count": {
            "type": "integer",
            "example": 12
          },
          "holidays": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Holiday"
            }
          }
        }
      },
      "DateResponse": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "is_holiday": {
            "type": "boolean"
          },
          "holiday": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Holiday"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "Year must be between 2025 and 2100"
          }
        }
      }
    }
  }
}