stefan.tollkuehn
dd4716faf4
- add license section, - add info about vibe coding at top - add information about contacts search GET - minor changes
116 lines
3.8 KiB
Markdown
116 lines
3.8 KiB
Markdown
# AToCal — Add To Calendar
|
|
|
|
> **Vibe-coded:** AToCal is written by Mistral AI's coding agent, not by hand.
|
|
> The maintainer sets the goals, makes the product decisions and tries the app
|
|
> out in the browser; there has been no independent human code review and
|
|
> no security audit.
|
|
|
|
A Nextcloud app that lets remote applications create events in the
|
|
authenticated user's Nextcloud Calendar via a simple link.
|
|
|
|
## How it works
|
|
|
|
```
|
|
remote app Nextcloud (atocal)
|
|
| |
|
|
| GET /apps/atocal/confirm |
|
|
| summary, start, end, ... |
|
|
|----------------------------->|
|
|
| | confirm page
|
|
|<-----------------------------|
|
|
| |
|
|
| POST /apps/atocal/create | (CSRF token from form)
|
|
|----------------------------->|
|
|
| | event in "Personal" calendar
|
|
|<-----------------------------| redirect to Calendar app
|
|
```
|
|
|
|
The remote app links the user to the confirm page. The user reviews
|
|
the event and submits the form. The event lands in a calendar the user
|
|
chooses. The user adds invitees/attendees to the event, who receive
|
|
an invitation, as long as the user owns the calendar.
|
|
After the event is created the browser opens the Calendar app.
|
|
|
|
## Routes
|
|
|
|
| Method | Path | Purpose |
|
|
|--------|------|---------|
|
|
| GET | `/apps/atocal/confirm` | Show confirmation page |
|
|
| POST | `/apps/atocal/create` | Create the event |
|
|
| GET | `/apps/atocal/contacts/search` | Contact search for the invitee input |
|
|
|
|
## Link parameters (GET `/confirm` and form POST `/create`)
|
|
|
|
| Parameter | Required | Rules |
|
|
|-----------|----------|-------|
|
|
| `summary` | yes | max 255 chars |
|
|
| `start` | yes | datetime-local, e.g. `2026-10-07T14:15` |
|
|
| `end` | yes | after `start`, same format |
|
|
| `description` | no | max 10000 chars |
|
|
| `location` | no | HTTPS URL |
|
|
| `url` | no | HTTPS URL; merged into description |
|
|
| `organizer` | no | email address; display info only |
|
|
|
|
The create form adds `calendarId` (selected calendar) and
|
|
`attendees` (emails, max 20).
|
|
|
|
Dates carry no timezone and are interpreted in the user's Nextcloud
|
|
timezone (server default as fallback).
|
|
|
|
## Organizer
|
|
|
|
The event's ICS `ORGANIZER` is the Nextcloud user's own email
|
|
address. Invitations to attendees are scheduled by the CalDAV
|
|
backend in the calendar owner's name, which only works when the
|
|
organizer matches the owner.
|
|
|
|
The `organizer` link parameter is shown on the confirm page as
|
|
meeting information and is used as `ORGANIZER` fallback only when
|
|
the user has no profile email — in that case no working
|
|
invitations may be sent, so profile emails should be set.
|
|
|
|
## Reminder
|
|
|
|
Every created event gets a display alarm 15 minutes before it starts
|
|
(`TRIGGER:-PT15M` VALARM). The reminder is not configurable.
|
|
|
|
Example:
|
|
|
|
```
|
|
https://cloud.example.com/apps/atocal/confirm?summary=Kickoff&start=2026-10-12T10:00&end=2026-10-12T11:00&location=https%3A%2F%2Fmeet.example.com%2Fkickoff
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- Nextcloud 34 or 35
|
|
- Calendar app enabled
|
|
- A writable calendar ("Personal" is preselected if present)
|
|
|
|
## Install
|
|
|
|
Copy this directory to the Nextcloud server as
|
|
`apps/atocal`, then:
|
|
|
|
```
|
|
occ app:enable atocal
|
|
```
|
|
|
|
## Structure
|
|
|
|
```
|
|
appinfo/info.xml app metadata
|
|
appinfo/routes.php routes
|
|
css/style.css page styles
|
|
js/invitees.js invitee input
|
|
l10n/*.json translations
|
|
lib/AppInfo/Application.php container setup
|
|
lib/Controller/CalendarController.php confirm/create logic
|
|
templates/confirm.php confirmation page
|
|
```
|
|
|
|
## Licence
|
|
|
|
AGPL-3.0-or-later, see LICENSE. AToCal comes without any warranty.
|
|
|
|
AToCal is an independent project and is not affiliated with any other product or company of a similar name.
|