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 details)

Uploaded Source

Built Distribution

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

Uploaded Python 3

File details

Details for the file jcalapi-0.1.9.tar.gz.

File metadata

  • Download URL: jcalapi-0.1.9.tar.gz
  • Upload date:
  • Size: 26.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for jcalapi-0.1.9.tar.gz
Algorithm Hash digest
SHA256 4411de69e243e9ad6856e2f685b8c9e35d9a3a7c22d0ae19e7793d2b0cfb206a
MD5 f8fb6e224951d3f92eb4b55a3ef20274
BLAKE2b-256 d8cbad29d93e59ae6ffd08d962c12d014e15faf55a6b504d8199cb84f64db01f

See more details on using hashes here.

File details

Details for the file jcalapi-0.1.9-py3-none-any.whl.

File metadata

  • Download URL: jcalapi-0.1.9-py3-none-any.whl
  • Upload date:
  • Size: 29.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for jcalapi-0.1.9-py3-none-any.whl
Algorithm Hash digest
SHA256 14f55dbf55965c4198f997ad44b560c5a964b60f48de75e7a0f9a3cf638c930c
MD5 ab73a4c1a7f128068761659e9c163252
BLAKE2b-256 f05dcdc69a64ad6a6bca8ee03a12788fab29a7683cacfe49415457cb878faa60

See more details on using hashes here.

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