Holidays for working hours

[eartharoid]

Suggested by @M4rlus:
Allow setting holidays, days which staff are expected to be unavailable.

I briefly considered how to handle holidays before but decided it wasn't necessary, but apparently, it is.
If today is a holiday, working hours are ignored and a message will be sent saying that staff are not working today.

This enhancement would require a new guild setting, so workingHours (which is currently [timezone, sunday, monday, ...]) should be split into multiple columns:

• workingHours ([sunday, monday, ...])
• workingHoursTimezone
• workingHoursCountry or workingHoursCalendar

Possible data sources

Nager.Date API

It's free, doesn't need an API key, supports over 100 countries, and would be very simple to implement.

/api/v3/IsTodayPublicHoliday/{countryCode} effeticely returns a boolean.
The problem is that it only returns true for global holidays, which is good, except when there are annoying inconsistencies between regions.

For example, as seen here:

• ❌ New Year's Day is not global; there's 4 different holidays:
  • 1st Jan in NIR
  • 2nd Jan in ENG and WLS
  • 2nd Jan in SCT
  • 3rd Jan in SCT
• ✅ Good Friday is global
• ❌ Easter Monday is not global
  • only a holiday in ENG, WLS, and NIR, not SCT
• ✅ Saint Andrew's Day is not global
  • only a holiday in SCT
  • now you have the reverse problem if your entire staff team is Scottish...

A workaround could be to use /api/v3/PublicHolidays/{year}/{countryCode} and filter them by "county", which would require another guild setting.

HolidayAPI

This is the best API I found (that works for multiple countries). The country parameter accepts regions as well, like GB and GB-ENG.
Unfortunately, only historical data is available for free.

M4rlus' original idea: .ics files

Allow setting the URL of a .ics file to subscribe to. This is a bit more difficult to implement as the bot needs to parse the iCalendar file, but it solves the regional inconsistencies problem and is also much more customisable.

officeholidays.com has accurate (for the UK at least) files for most countries, and even for different regions, so both https://www.officeholidays.com/ics-clean/united-kingdom and https://www.officeholidays.com/ics-clean/united-kingdom/england work.

Being customisable (because you can upload your own file somewhere and serve it over HTTP), this also works better if you have an international staff team. You could make a file that only includes holidays that are the same in most countries, so for example, the bot won't incorrectly say there are no staff available because it is a bank holiday in one country, whilst it is a normal day everywhere else.

[RooRay]

The Nager.Date API is probably going to be a no-no since the New Year's Day stuff is completely out of whack, and Easter Monday is still a holiday up here in Scotland 😄

HolidayAPI could work as a default, as not every National Holiday changes date every year. However, this causes problems with events such as Thanksgiving which is on the fourth Thursday of November.

.ics files are probably our best bet here since they will be the most accurate and allow people to add in their own holidays, like if a staff team doesn't work Sundays, for example.

Alternatively, we could do a mix of .ics files and the HolidayAPI to account for both holidays that change and ones that don't? Or maybe allow people to make timesheets via the portal that specifies what days they do and don't work.

[M4rlus]

Nager.Date is quite relaxed for German teams, because Germany has for whatever reason different regulations in individual states. However, I find individual holidays such as a "Labor Day" relatively pointless, because here in Germany everyone would continue to work on this day. There must be some function that exclusively issues special holidays such as Easter, Christmas, New Year, New Year's Eve or otherwise.

.ics is still the best solution, but I think many will have a problem with it.

@RooRay 's idea to add a region for each staff member is probably still a good idea, but you would have to use an API like HoldayAPI or Nager.Date, because .ics just doesn't make sense and is way too complicated.

[eartharoid]

https://github.com/eartharoid/holidays