private events and event limit on api updates

src/api/events.md

@@ -175,6 +175,8 @@ The only important difference: The `event_group` field is not allowed.
 Mind the further lmitations, also present on creation via API.
 
 For the status, mind that if an event gets set to draft on the application UI, you cannot publish it via API!
+
+**For every 5th update, we also deduct 1 event credit to prevent abuse!**
 :::
 
 <br />

src/api/groups.md

@@ -101,6 +101,8 @@ Updating a group follows the same rules as creating one.
 You can only change the subscription setting as long as there are no events linked to the group!
 
 For the status, mind that if a group gets set to draft on the application UI, you cannot publish it via API!
+
+**For every 5th update, we also deduct 1 event credit to prevent abuse!**
 :::
 
 <br />

src/api/miscellaneous.md

@@ -1,5 +1,15 @@
 # Miscellaneous
 
+## Retrieve ics file body
+
+```
+GET /ics/:id
+```
+
+Providing the proKey of the respective event, you can get the body for the ics file.
+
+Use this to create the ics file on your side without relying on any auto-generation on our side (which would result in an ics file, placed on a public storage).
+
 ## List RSVP replies
 
 ```

src/application-manual/troubleshooting.md

@@ -40,6 +40,18 @@ The inline RSVP form adapts to its surrounding container.
 
 This usually already leads to it taking all the available width. Based on the used css, however, you might want to add something like `style="width:100%;"` to this container. For example, if the container uses a flexbox, explictly specifying the width is mandatory.
 
+## How can I make sure there is no data publicly available on the internet
+
+Per default, the event data and ics file are available to everybody who knows the link to it. We encourage search engines to not pick it up, but cannot guarantee this.
+
+This is basically necessary for things like email links or even the Add to Calendar Button to work properly.
+
+If you do not want this to happen - because, for example, you put sensitive information into the event details - you can set an event (or group) to private. Click the flap on the top of the big box at the beginning of the details page.
+
+A private event has no public ics file or landingpage. The Add to Calendar Button will also not work as it requires to pull the information via the web. However, you can still [generate ics files via our API](/api/miscellaneous.html#retrieve-ics-file-body). 
+
+This makes it an ideal case for [dynamic checkout flows](/recipes/dynamic-checkout.html) with sensitive information!
+
 ## The Add to Calendar Button dropdown is behind other elements
 
 The dropdown gets rendered next to the button element with a higher z index.

src/de/api/events.md

@@ -175,6 +175,8 @@ Der einzig wichtige Unterschied: Das `event_group`-Feld ist hier nicht erlaubt.
 Beachte die Einschränkungen, die auch für die Erstellung via API gelten.
 
 Beachte ferner, dass du den Status über die Anwendungs-Oberfläche auf "Entwurf", über die API aber nicht auf "Veröffentlicht" setzen kannst!
+
+**Für jedes 5te Update ziehen wir zudem 1 Event-Credit ab, um Missbrauch vorzubeugen!**
 :::
 
 <br />

src/de/api/groups.md

@@ -101,6 +101,8 @@ Die Aktualisierung einer Gruppe folgt den gleichen Regeln wie die Erstellung ein
 Die "subscription"-Einstellung lässt sich nur ändern, solange noch keine Events mit der Gruppe verknüpft sind!
 
 Beachte, dass du den Status über die Anwendungs-Oberfläche auf "Entwurf", über die API aber nicht auf "Veröffentlicht" setzen kannst!
+
+**Für jedes 5te Update ziehen wir zudem 1 Event-Credit ab, um Missbrauch vorzubeugen!**
 :::
 
 <br />

src/de/api/miscellaneous.md

@@ -1,5 +1,15 @@
 # Verschiedenes
 
+## ics-Datei-Inhalt abrufen
+
+```
+GET /ics/:id
+```
+
+Indem du den proKey des jeweiligen Events angibst, kannst du den "Body" der zugehörigen ics-Datei abrufen.
+
+Nutze dies, um die ics-Datei in deinem System zu erstellen - ohne Abhängigkeit zur Generierung auf unserer Seite (was dazu führt, dass die ics-Datei auf einem öffentlich erreichbaren Storage abgelegt wird).
+
 ## RSVP-Rückmeldungen listen
 
 ```

src/de/application-manual/troubleshooting.md

@@ -40,6 +40,18 @@ Das Inline-RSVP-Formular passt sich an den umgebenden Container an.
 
 Das führt normalerweise bereits dazu, dass es die gesamte verfügbare Breite einnimmt. Abhängig vom verwendeten CSS musst du jedoch möglicherweise etwas wie `style="width:100%;"` zu diesem Container hinzufügen. Wenn der Container zum Beispiel ein Flexbox verwendet, ist das Angeben der Breite (`width`) obligatorisch.
 
+## Wie kann ich sicherstellen, dass keine Daten öffentlich im Internet verfügbar sind
+
+Standardmäßig sind die Eventdaten und die ics-Datei für jeden verfügbar, der den Link dazu kennt. Wir ermutigen Suchmaschinen, diese nicht aufzurufen, können dies jedoch nicht garantieren.
+
+Dies ist für Funktionen wie E-Mail-Links oder den Add-to-Calendar-Button notwendig, um ordnungsgemäß zu funktionieren.
+
+Wenn du nicht möchtest, dass dies geschieht - zum Beispiel, weil du sensible Informationen in die Eventdetails einfügst - kannst du ein Event (oder eine Gruppe) auf privat setzen. Klicke dazu auf die Klappe oben am großen Kasten zu Beginn der Detailseite.
+
+Ein privates Event hat keine öffentliche ics-Datei oder Landingpage. Der Add-to-Calendar-Button funktioniert ebenfalls nicht, da er die Informationen über das Web abrufen muss. Du kannst jedoch weiterhin [ics-Dateien über unsere API generieren](/de/api/miscellaneous.html#retrieve-ics-file-body).
+
+Das macht es zu einem idealen Fall für [dynamische Checkout-Flows](/de/recipes/dynamic-checkout.html) mit sensiblen Informationen!
+
 ## Das Dropdown des Add to Calendar Buttons verschwindet hinter anderen Elementen
 
 Das Dropdown wird direkt nach dem Button-Element mit einem höheren z-Index gerendert.

src/de/recipes/dynamic-checkout.md

@@ -1,7 +1,6 @@
 ---
 outline: [2,3]
 ---
-
 # Add to Calendar Buttons in einem dynamischen Checkout-Prozess
 
 Der Verkauf von Termin-gebundenen Artikeln (bspw. Konzert-Tickets) oder einfach die Vereinbarung von Terminen über einen Buchungsprozess sind übliche Szenarien für viele Unternehmen.
@@ -16,27 +15,50 @@ Du solltest einen Style sowie eine allgemeine Event-Gruppe vorbereiten. Letztere
 
 Abgesehen davon wird alles andere über die API abgewickelt - du musst dafür natürlich einen API-Key erstellen.
 
+::: warning Achtung bei sensiblen Daten!
+Wenn du ein Event erstellst, generieren wir automatisch eine ics-Datei und stellen dir eine Landingpage und mehr zur Verfügung.
+Diese Dinge sind von Natur aus "öffentlich" zugänglich. Jeder mit dem entsprechenden Link kann diese Informationen abrufen. Obwohl die Daten damit nicht völlig "offen" ist, kann es ein Risiko darstellen, wenn du sensible Informationen in den Detailinformationen des Events nutzt. Dies kann ein Problem bei manchen Checkout-Flows sein.
+
+**Du kannst [das verhindern](/de/application-manual/troubleshooting.html#how-can-i-make-sure-there-is-no-data-publicly-available-on-the-internet) indem du das Event auf "privat" setzt.**
+
+In der folgenden Anleitung zeigen wir auch den Prozess-Fluß mit einem privaten Event.
+:::
+
 ## 🧱 Einrichtung
 
 Die Einrichtung dieses Ablaufs erfordert etwas mehr Arbeit, da du dies in deine bestehenden Backend-Abläufe integrieren musst!
 
 **Der generelle Ablauf visualisiert:**
 
-![Editor](/screenshots/checkout-flow.svg)
+<br />
+
+![Checkout-Flow-mit-ics-Datei-und-Add-to-Calendar-Button](/screenshots/checkout-flow.svg)
+
+<br /><br />
+
+**Wenn du ein Event als _privat_ markierst sieht der Flow ein klein wenig anders aus:**
 
 <br />
 
+![Geschuetzter-Checkout-Flow-mit-ics-Datei-und-Add-to-Calendar-Button](/screenshots/checkout-flow-secured.svg)
+
+<br /><br />
+
 **Hier kommt eine Liste der nötigen Schritte:**
 
 1. Erstelle einen Style und bereite alles für einen potenziellen Add to Calendar Button vor, damit dieser gut aussieht (überspringe diesen Schritt, wenn du nur mit ics-Dateien arbeiten möchtest).
 2. Erstelle ein Landingpage-Template und verknüpfe es mit dem Style. Das ist wichtig, wenn du E-Mail-Links verwendest; oder wenn du einfach eine schöne Veranstaltungs-Landingpage teilen möchtest (kann auch für das Support-Team nützlich sein, wenn ein Benutzer Hilfe beim Speichern des Events benötigt).
 3. Erstelle einen API-Key (auf der Seite der Organisationseinstellungen).
 4. Erstelle eine Event-Gruppe (mit Kalender-Abonnement auf "Nein"), die alle zukünftigen Veranstaltungen beinhalten wird.
 5. Lies die [API-Dokumentation über die Eventerstellung](/de/api/events.html#add-an-event).
-6. Erstelle in deinem Backend eine Funktion, die ein Event über die Add to Calendar PRO API basierend auf den Daten, die du für den Benutzer hast, erstellt. Wir empfehlen, in diesem Fall auch den Organizer und den Attendee festzulegen (bei manchen Systemen wird das Event dadurch automatisch zum Kalender des Benutzers hinzugefügt, sobald eine E-Mail mit der ics-Datei geöffnet wird)! Die Response beinhaltet eine ID (der ProKey des Events).
-7. Verwende diese ID, um die generierte ics-Datei beim Senden einer Bestätigungs-E-Mail abzurufen und an die E-Mail anzufügen.
-8. Verwende diese ID, um Add to Calendar Links in dieser Bestätigungs-E-Mail zu integrieren.
-9. Verwende diese ID, um einen schönen Add to Calendar Button auf der "Danke"-Seite nach dem Checkout zu rendern.
+6. Erstelle in deinem Backend eine Funktion, die ein Event über die Add to Calendar PRO API basierend auf den Daten, die du für den Benutzer hast, erstellt. Wir empfehlen, in diesem Fall auch den Organizer und den Attendee festzulegen (bei manchen Systemen wird das Event dadurch automatisch zum Kalender des Benutzers hinzugefügt, sobald eine E-Mail mit der ics-Datei geöffnet wird)! _Definiere das Event als "privat", falls nötig._ Die Response beinhaltet eine ID (der ProKey des Events).
+7. Bei regulären Events:
+   1. Verwende diese ID, um die generierte ics-Datei beim Senden einer Bestätigungs-E-Mail abzurufen und an die E-Mail anzufügen.
+   2. Verwende diese ID, um Add to Calendar Links in dieser Bestätigungs-E-Mail zu integrieren.
+   3. Verwende diese ID, um einen schönen Add to Calendar Button auf der "Danke"-Seite nach dem Checkout zu rendern.
+8. Bei als "privat" markierten Events:
+   1. Verwende diese ID, um den Body-Inhalt der [ics-Datei via API abzurufen](/de/api/miscellaneous.html#retrieve-ics-file-body), die Datei damit selbst zu generieren und zu versenden.
+   2. Bei privaten Events kannst du keine Add to Calendar Links nutzen. Add to Calendar Buttons funktionieren über den üblichen Weg ebenfalls nicht. Du kannst allerdings die sowieso (für die Anlage des Events) gegebenen Daten nutzen, um einen Button gemäß dem Open-Source-Schema zu erstellen (siehe [add-to-calendar-button.com](https://add-to-calendar-button.com/de))
 
 ### Schema für ics-Dateien
 
@@ -54,7 +76,6 @@ https://go.caldn.net/:id/o/:type
 
 Mit `type` als "apple", "google", "ical", "ms365", "outlookcom", "msteams" oder "yahoo".
 
-
 ## ❇️ Weiter gedacht
 
 Du fragst dich vielleicht, wie du mit Entwicklungs- oder Staging-Umgebungen umgehen kannst!

src/recipes/dynamic-checkout.md

@@ -16,27 +16,50 @@ You should prepare a style as well as a general event group (which acts as some
 
 Besides that, everything else will happen via the API - you need to create an API key for that case, of course.
 
+::: warning Mind sensitive information!
+When you create an event, we automatically generate an ics file and provide you with a landingpage and more.
+Those things are public by nature. Everybody with a respective link can retrieve this information. So, it is not completely "open", it can be a risk when placing sensitive information into the event's detail information. This can be a problem for checkout flows.
+
+**You can [prevent this](/application-manual/troubleshooting.html#how-can-i-make-sure-there-is-no-data-publicly-available-on-the-internet) by setting the event to "private".**
+
+In the following guide, we also highlight the process with a private event.
+:::
+
 ## 🧱 Setting it up
 
 The setup of this flow requires some more work as you will need to weave this into your existing backend flows!
 
-**Have a look at the general scheme:**
+**Have a look at the general scheme (public):**
+
+<br />
 
-![Editor](/screenshots/checkout-flow.svg)
+![checkout-Flow-with-ics-file-and-add-to-calendar-button](/screenshots/checkout-flow.svg)
+
+<br /><br />
+
+**When you keep the event _private_, the flow would look slightly different:**
 
 <br />
 
+![secured-checkout-Flow-with-ics-file-and-add-to-calendar-button](/screenshots/checkout-flow-secured.svg)
+
+<br /><br />
+
 **No here comes a list of the steps you need to take:**
 
 1. Create a style and prepare everything for a potential Add to Calendar Button to look good (skip this if you are only up for ics files).
 2. Create a landingpage template and link it to the style. This is important if you want to use email links; or if you simply want to be able to share a nice event landingpage (can be a nice thing for the support team, when a user needs help saving the event).
 3. Create an API key (at the organization settings page).
 4. Create an event group (with subscription set to "no"), which will hold all future events.
 5. Read the [API documentation about event creation](/api/events.html#add-an-event).
-6. At your backend, create a function, which creates an event via the Add to Calendar PRO API based on the data you have for the user. We recommend to also set the organizer and attendee in this case (at some systems, this adds the event automatically to the user's calendar, as soon as an email with the ics file is opened)! The response includes an id, which is the ProKey of the event.
-7. Use this id to pull and add the generated ics file when sending a confirmation email.
-8. Use this id to add Add to Calendar links at this confirmation email.
-9. Use this id to render a nice Add to Calendar Button at the "Thank you" page after the checkout.
+6. At your backend, create a function, which creates an event via the Add to Calendar PRO API based on the data you have for the user. We recommend to also set the organizer and attendee in this case (at some systems, this adds the event automatically to the user's calendar, as soon as an email with the ics file is opened)! _Set the event to private if necessary._ The response includes an id, which is the ProKey of the event.
+7. With regular events:
+   1. Use this id to pull and add the generated ics file when sending a confirmation email.
+   2. Use this id to add Add to Calendar links at this confirmation email.
+   3. Use this id to render a nice Add to Calendar Button at the "Thank you" page after the checkout.
+8. For events marked as "private":
+   1. Use this ID to retrieve the body content of the [ics file via API](/api/miscellaneous.html#retrieve-ics-file-body), generate the file yourself, and send it.
+   2. For private events, you cannot use Add to Calendar links. Add to Calendar buttons do not work via the usual method either. However, you can use the data already provided (for creating the event) to create a button according to the open-source schema (see [add-to-calendar-button.com](https://add-to-calendar-button.com/de))
 
 ### Scheme for ics files