Skip to main content

Local calendar caching and JSON API

Project description

📅 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

🔑 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
  1. Navigate into the cloned repository
cd jcalapi
  1. Setup the environment
poetry install

Alternatives:

  • Use devenv
  • Try the provided devcontainer (untested, generated by devenv)

📄 License

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jcalapi-0.1.9.tar.gz (26.4 kB view hashes)

Uploaded Source

Built Distribution

jcalapi-0.1.9-py3-none-any.whl (29.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page