Metadata-Version: 2.1
Name: jcalapi
Version: 0.1.5
Summary: Local calendar caching and JSON API
Home-page: https://github.com/pschmitt/jcalapi
License: GPL-3
Author: Philipp Schmitt
Author-email: philipp@schmitt.co
Requires-Python: >=3.10,<4.0
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: asynccli (>=0.1.3,<0.2.0)
Requires-Dist: atlassian-python-api (>=3.38.0,<4.0.0)
Requires-Dist: beautifulsoup4 (>=4.12.2,<5.0.0)
Requires-Dist: diskcache (>=5.6.1,<6.0.0)
Requires-Dist: environs (>=9.5,<11.0)
Requires-Dist: exchangelib (>=5.0.3,<6.0.0)
Requires-Dist: fastapi (>=0.96,<0.110)
Requires-Dist: fastapi-utils (>=0.2.1,<0.3.0)
Requires-Dist: httpx (>=0.24.1,<0.27.0)
Requires-Dist: icalendar (>=5.0.7,<6.0.0)
Requires-Dist: loguru (>=0.7.0,<0.8.0)
Requires-Dist: python-dateutil (>=2.8.2,<3.0.0)
Requires-Dist: python-multipart (>=0.0.6,<0.0.8)
Requires-Dist: recurring-ical-events (>=2.0.2,<3.0.0)
Requires-Dist: uvicorn[standard] (>=0.22,<0.28)
Requires-Dist: xdg (>=6.0.0,<7.0.0)
Description-Content-Type: text/markdown

# 📅 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
- [Poetry](https://python-poetry.org)

### 🔑 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](./.envrc-sample) for an example.

### 💾 Installation

```shell
# pip
pip install --user jcalapi

# pipx
pipx install jcalapi
```

### 🏃 Usage

You can run the application directly using Python:

```shell
python -m jcalapi
```

### 🐳 Blablabla, Docker?

```shell
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 \
  ghcr.io/pschmitt/jcalapi
```

## 📚 API Usage

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

```shell
curl http://localhost:7042/today
```

This will return a JSON response with the events data:

```json
[
  {
    "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:

```shell
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):

```shell
curl http://localhost:7042/meta
```

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

```shell
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
```shell
git clone https://github.com/pschmitt/jcalapi.git
```

2. Navigate into the cloned repository
```shell
cd jcalapi
```

3. Setup the environment
```shell
poetry install
```

## 📄 License

This project is licensed under the [GNU General Public License v3.0](LICENSE).

