📅 jcalapi

jcalapi is a local calendar cache and JSON API that interacts with Exchange and Confluence calendars. It fetches events and returns them in a JSON format, making it easy to integrate calendar data into other systems.

🚀 Getting Started

📋 Prerequisites

• Python
• uv (or Nix with flakes)

🔑 Setting Up Credentials

To use jcalapi, you'll need to provide credentials for accessing your Exchange or Confluence calendars. These credentials should be stored in a secure location, and you should ensure that they are not exposed in your code or version control system.

For Exchange, you'll need your username and password. For Confluence, you'll need your API token.

See .envrc-sample for an example.

💾 Installation

# pip
pip install --user jcalapi

# pipx
pipx install jcalapi

🏃 Usage

You can run the application directly using Python:

python -m jcalapi

🐳 Blablabla, Docker?

docker run -it --rm -p 127.0.0.1:7042:7042 \
  -e ONFLUENCE_URL=https://confluence.example.com \
  -e CONFLUENCE_USERNAME=john.doe \
  -e CONFLUENCE_PASSWORD=XXX \
  -e EXCHANGE_USERNAME=john.doe@example.com \
  -e EXCHANGE_PASSWORD=XXX \
  -e GOOGLE_CREDENTIALS=/config/xxx.apps.googleusercontent.com.json \
  -e GOOGLE_CALENDAR_REGEX='^Work '
  ghcr.io/pschmitt/jcalapi

📚 API Usage

The API provides endpoints for fetching calendar events. Here's an example of how to use it:

curl http://localhost:7042/today

This will return a JSON response with the events data:

[
  {
    "uid": "event1",
    "backend": "exchange",
    "calendar": "calendar1",
    "organizer": "organizer1",
    "attendees": {
      "name": "hisname",
      "email": "his@email.com",
      "optional": false,
      "response": "Accept"
    },
    "summary": "event1 summary",
    "description": "event1 description",
    "body": "event1 body",
    "location": "event1 location",
    "start": "2023-06-06T00:00:00",
    "end": "2023-06-06T01:00:00",
    "whole_day": false,
    "is_recurring": false,
    "categories": [
      "Cat1",
      "Cat2"
    ],
    "status": "confirmed",
    "extra": {
      "conference_type": "Teams",
      "meeting_workspace_url": "https://teams.microsoft.com/l/meetup-join/...",
      "net_show_url": "https://teams.microsoft.com/l/meetup-join/..."
    },
    "conference_url": "https://teams.microsoft.com/l/meetup-join/..."
  },
  ...
]

To fetch events for tomorrow, you can use the /tomorrow endpoint:

curl http://localhost:7042/tomorrow

This will return a JSON response with the events data for tomorrow.

The /meta endpoint provides metadata about the backends (Confluence/Exchange):

curl http://localhost:7042/meta

The /reload endpoint allows you to reload the calendar data:

curl -X POST http://localhost:7042/reload

🤝 Contributing

Contributions are welcome! Please feel free to submit a pull request.

🧑‍💻 Development setup

1. Clone the repository

git clone https://github.com/pschmitt/jcalapi.git

2. Navigate into the cloned repository

cd jcalapi

3. Setup the environment

uv sync --group dev  # with Nix devshell, dev tools are already available

Alternatives:

• Use Nix flakes: nix develop drops you into a shell with dev tools and uv; run uv sync --group dev to install deps locally and uv run python -m jcalapi

📄 License

This project is licensed under the GNU General Public License v3.0.