Update Google Calendar integration

[Niloth-p]

Fixes: #847
Fixes: #850 (to auto-close absorbed PRs)
Fixes: #851 (to auto-close absorbed PRs)

Please don't get intimidated by the number of commits, it's an attempt to make things more readable and easy to review, not less so.

Updates to the integration - summarized

Major changes in the behavior of the integration include:

Bugs

• Replace deprecated oauth2client library, which prevented the script from being used.
• Update outdated send_message parameters that would generate errors when the script sent Zulip messages.
• Previously, the integration script would only run up to 1 hour before erroring out, as the auth token will always expire in 1 hour, and the user needs to run the get-google-credentials script to re-generate the auth token.
• Previously, the zuliprc of the user was needed, and hence the user could only run this integration locally and just for themselves. Now, a generic bot's zuliprc is sufficient. The integration can be used to send reminders from shared/public calendars in public channels.
• Can now be run from a server. Previously, the OAuth process would require interaction with the browser for authorization.

Integration Features

• Can now send reminders to channels (previously, was restricted to DMs).
• Added more details to the reminders being sent. Previously, only "title starts at x" was sent. Now, messages include links to the calendar, google meet links to their call, the event description, location, etc.

Security Improvements

• user's zuliprc -> bot's zuliprc.
• Narrow the permission scope to calendar events.

Usability Features

• Vastly improved the usage help.
  • No longer require passing in the user's email to the command directly.
• Previously required running 3 different commands to run the integration. Now, all in one script.
• Added error handling for unaddressed cases.
• Vastly improved customization of the integration. Options can be passed in either through command line flags or via settings in the .zuliprc file.
  • Pass in custom paths to the two auth-related files.
  • Choose the channel and topic name.
  • Use your own formatting for the message.
• Previously, all reminder messages were being printed to the terminal. Now, key processes of the integration are logged when the --verbose flag is set.

Developer Features - Vastly improved the code readability. All decisions are explained either in the comments or the commit messages (which add only 1 feature at a time, to clarify the intention, and create verifiable history).

Failing CI is unrelated

The failing CI seems to be unrelated to the changes in this PR.

Error:

ERROR:  schema "pgroonga" does not exist

Error running a subcommand of /__w/python-zulip-api/python-zulip-api/server/tools/lib/provision_inner.py: tools/setup/postgresql-init-dev-db

Which has nothing to do with this PR.

User Experience - Feedback welcome!

Includes the message template, and the default file location

• Do we want to change the default location (and filename) of the client secret file that the user needs to download, (rename) and place before running the integration? It is currently set to ~/client_secret.json.
  • Google API docs sometimes mention it as credentials.json. But, we went against naming it that way to avoid confusing with other credentials.
  • It could also help to not pollute the ~ directory with a vague file name like client_secret.json.
  • I've left the "Improve CLIENT_SECRET_FILE occurrences" commit a bit bare, with some minor and miscellaneous changes, so that we can add to it, if we want to change the default file path or file name.
• Usage help:
  
• Formatting of the message being sent:
  

{title}, at {location}, is scheduled from {start} to {end}.
> {description}
Join call.

• The title is linked to open the event in the calendar.
• If there's a location included - append ", at {location}".
• If the event is an all-day event - use "is today" instead of "is scheduled from {start} to {end}."
• The description is placed inside a quote.
• "Join call." is linked to the Google Meet call link, if any.
• The reason I went with "is scheduled from" is because I've been considering adding support for the status of the event, which could be tentative. But that has been dropped for the moment.

Manual and automated testing

• Events API Link for reviewers
• Will update the integration doc a bit later, for reference for manual testing.
  • I'm considering posting just the main instructions here, because updating that PR fully may take a while longer.
• It would have definitely been awesome to have automated tests, for these many commits, but kept putting it off since I wasn't sure they were a priority for the moment. Did not expect the PR to keep growing to 27 commits. Though I considered it, I decided not to wait until the tests are added, to push this branch.

Self-review checklist

• Self-reviewed the changes for clarity and maintainability
  (variable names, code reuse, readability, etc.).

Communicate decisions, questions, and potential concerns.

• Explains differences from previous plans (e.g., issue description).
• Highlights technical choices and bugs encountered.
• Calls out remaining decisions and concerns.
• Automated tests verify logic where appropriate.

Individual commits are ready for review (see commit discipline).

• Each commit is a coherent idea.
• Commit message(s) explain reasoning and motivation for changes.

Completed manual review and testing of the following:

• Visual appearance of the changes.
• Responsiveness and internationalization.
• Strings and tooltips.
• End-to-end functionality of buttons, interactions and flows.
• Corner cases, error conditions, and easily imagined bugs.

[alya]

@laurynmm Are you up for reviewing this one? I haven't tried to wrap my head around it. Not specifically a release goal.