From 29d8a35bcbda4302c4c1361291b650a5b2e0d195 Mon Sep 17 00:00:00 2001
From: Jens Kuerschner <mail@jenskuerschner.de>
Date: Wed, 13 Dec 2023 18:06:38 +0100
Subject: [PATCH] minor updates to API

---
 .vitepress/config.ts                      |  2 -
 src/api/events.md                         | 86 ++++++++++++++++++++++-
 src/api/groups.md                         | 30 ++++++++
 src/api/miscellaneous.md                  | 41 +++++++++++
 src/api/rsvp.md                           | 30 ++++++++
 src/api/styles.md                         |  2 -
 src/automation-integration/webhooks.md    | 35 ++++++++-
 src/de/api/styles.md                      |  2 -
 src/de/automation-integration/webhooks.md | 37 +++++++++-
 src/integration/general.md                |  6 ++
 10 files changed, 262 insertions(+), 9 deletions(-)
 delete mode 100644 src/api/styles.md
 delete mode 100644 src/de/api/styles.md

diff --git a/.vitepress/config.ts b/.vitepress/config.ts
index 090235d..909e3f7 100644
--- a/.vitepress/config.ts
+++ b/.vitepress/config.ts
@@ -71,7 +71,6 @@ export default {
               { text: 'Authentication', link: '/de/api/auth' },
               { text: 'Gruppen', link: '/de/api/groups' },
               { text: 'Events', link: '/de/api/events' },
-              { text: 'Styles', link: '/de/api/styles' },
               { text: 'RSVP', link: '/de/api/rsvp' },
               { text: 'Verschiedenes', link: '/de/api/miscellaneous' },
             ]
@@ -192,7 +191,6 @@ export default {
           { text: 'Authentication', link: '/api/auth' },
           { text: 'Groups', link: '/api/groups' },
           { text: 'Events', link: '/api/events' },
-          { text: 'Styles', link: '/api/styles' },
           { text: 'RSVP', link: '/api/rsvp' },
           { text: 'Miscellaneous', link: '/api/miscellaneous' },
         ]
diff --git a/src/api/events.md b/src/api/events.md
index ef818c4..6c057ba 100644
--- a/src/api/events.md
+++ b/src/api/events.md
@@ -7,7 +7,7 @@
 GET /event/:id
 ```
 
-Reading an event does not allow for any additional parameters.
+Reading an event does not allow for any additional parameters. It only takes the proKey/id in the request url.
 It simply provides you with all data for a specific event.
 
 ### Potential response
@@ -63,20 +63,104 @@ It simply provides you with all data for a specific event.
 ]
 ```
 
+<br />
+
 ## Add an event
 
 ```
 POST /event
 ```
 
+Creating a new event requires you to at least provide the following fields in the body:
+
+```json
+{
+    "event_group": "prokey-of-event-group", // gets returned as "id", when creating a group
+    "dates": [{
+        "name": "Title of the date",
+        "startDate": "2024-12-24",
+        "timeZone": "America/Los_Angelese" // not required, but highly recommended
+    }],
+}
+```
+
+Instead of `event_group`, you can also use `new_event_group_name`, which takes a string. This will create a new group with the provided name instead of linking the event to an existing one.
+
+Going further, you can add more dates to the array (= multi-date event) and add all fields, which are also present in the application's UI.
+
+::: warning Limitations
+Mind limitations, like recurrence not allowing for multiple dates, etc.
+We recommend to create a potential setup in the application first, before building it via the API.
+Additionally, the API does not allow to set the status of an event - it will always be published on creation.
+:::
+
+### Potential request with all fields
+
+```json
+{
+    "event_group": "prokey-of-event-group", // gets returned as "id", when creating a group
+    "dates": [{
+        "name": "Title of the date",
+        "description": "<p>An event description</p>", // allowing for <p>, <strong>, <em>, <u>, <h1>, <h2>, <h3>, <h4>, <ul>, <ol>, <li>, <a>
+        "startDate": "2024-12-24",
+        "startTime": "14:45",
+        "endDate": "2024-12-24",
+        "endTime": "16:15",
+        "timeZone": "America/Los_Angelese", // not required, but highly recommended
+        "location": "World Wide Web",
+        "status": "CONFIRMED", // or "TENTATIVE" or "CANCELLED"
+        "availability": "free", // or "busy"
+        "organizer_name": "Jack",
+        "organizer_email": "jack.frost@email.com",
+        "attendee_name": "Santa",
+        "attendee_email": "santa.claus@north.pole"
+    }],
+    "title_event_series": "Title for an event series if >1 date",
+    "simplified_recurrence": true, // set false, if you go for the "recurrence" field, which takes an RRULE; and true if you use the other recurrence fields
+    "recurrence": "RRULE:...",
+    "recurrence_simple_type": "daily", // or: "weekly", "monthly", "yearly",
+    "recurrence_interval": 1,
+    "recurrence_byDay": "2MO,TU", // example for the second Monday and each Tuesday
+    "recurrence_byMonth": "1,2,12", // example for Jan, Feb, and Dec
+    "recurrence_byMonthDay": "3,23", // example for the 3rd and 23rd day of the month
+    "recurrence_count": 10, // example: repeat 10 times
+    "recurrence_weekstart": "MO", // example for Monday
+    "layout": "id-of-a-style-template", // take the id from the url in the application
+    "iCalFileName": "overriding the ics file name",
+    "rsvp": true,
+    "rsvp_block": "id-of-an-rsvp-block", // take the id from the url in the application or the response when creating an rsvp block via API
+    "cta": true,
+    "cta_block": "id-of-a-cta-block", // take the id from the url in the application
+    "hide_button": false
+}
+```
+
+
+<br />
+
 ## Update an event
 
 ```
 PATCH /event/:id
 ```
 
+Updating an event follows the same rules as creating one.
+
+The only important difference: The `event_group` field is not allowed.
+
+::: warning Limitations
+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!
+:::
+
+<br />
+
 ## Delete an event
 
 ```
 DELETE /event/:id
 ```
+
+Deleting an event is simple. Only provide the id/prokey and it gets removed.
+
+**Be careful with this call!**
diff --git a/src/api/groups.md b/src/api/groups.md
index 80868fc..dfa0d8b 100644
--- a/src/api/groups.md
+++ b/src/api/groups.md
@@ -1,2 +1,32 @@
 
 # Groups API
+
+## Get a group
+
+```
+GET /group/:id
+```
+
+<br />
+
+## Add a group
+
+```
+POST /group
+```
+
+<br />
+
+## Update a group
+
+```
+PATCH /group/:id
+```
+
+<br />
+
+## Delete a group
+
+```
+DELETE /group/:id
+```
diff --git a/src/api/miscellaneous.md b/src/api/miscellaneous.md
index 79cd72f..32ee86a 100644
--- a/src/api/miscellaneous.md
+++ b/src/api/miscellaneous.md
@@ -1,2 +1,43 @@
 
 # Miscellaneous
+
+## List RSVP answers
+
+```
+GET /rsvp-answers/:id
+```
+
+Providing the proKey/id of the respective event, you can get a list of all connected RSVP answers/replies.
+
+### Potential response
+
+```json
+[
+    {
+        "id": "id-of-the-answer-1",
+        "status": "undecided",
+        "email": "john.doe@email.com",
+        "amount": 1,
+        "payload": {
+            "required_check": true,
+            "first_name": "John",
+            "last_name": "Doe"
+        },
+        "date_created": "2023-12-07T08:58:47.510Z",
+        "date_updated": "2023-12-09T16:46:24.381Z"
+    },
+    {
+        "id": "id-of-the-answer-2",
+        "status": "confirmed",
+        "email": "jane.doe@email.com",
+        "amount": 2,
+        "payload": {
+            "required_check": true,
+            "first_name": "Jane",
+            "last_name": "Doe"
+        },
+        "date_created": "2023-11-21T15:54:09.823Z",
+        "date_updated": "2023-12-03T19:30:00.314Z"
+    }
+]
+```
diff --git a/src/api/rsvp.md b/src/api/rsvp.md
index edd90fb..698cf7c 100644
--- a/src/api/rsvp.md
+++ b/src/api/rsvp.md
@@ -1,2 +1,32 @@
 
 # RSVP API
+
+## Get an RSVP
+
+```
+GET /rsvp-block/:id
+```
+
+<br />
+
+## Add an RSVP
+
+```
+POST /rsvp-block
+```
+
+<br />
+
+## Update an RSVP
+
+```
+PATCH /rsvp-block/:id
+```
+
+<br />
+
+## Delete an RSVP
+
+```
+DELETE /rsvp-block/:id
+```
diff --git a/src/api/styles.md b/src/api/styles.md
deleted file mode 100644
index bb74e2c..0000000
--- a/src/api/styles.md
+++ /dev/null
@@ -1,2 +0,0 @@
-
-# Styles API
diff --git a/src/automation-integration/webhooks.md b/src/automation-integration/webhooks.md
index 290bbb2..90fdadc 100644
--- a/src/automation-integration/webhooks.md
+++ b/src/automation-integration/webhooks.md
@@ -1,2 +1,35 @@
-
 # Making use of the integrated Webhooks
+
+You can use webhooks to ping any other service or system, when things change at your Add to Calendar PRO events.
+
+Per default, we send all data of the trigger element as JSON object with the key "element_data"; but you can also specify very custom payloads.
+
+## Potential Use Cases
+
+* Additionally sending RSVP sign-ups to your CMS.
+* Track the creation of events in your analytics tool to monitor your internal usage.
+
+## How it works
+
+Create a new webhook at the application.
+There, you can specify all the relevant paramters:
+
+
+| Field           | Content                                                                                                                                                                                                                                                                                                                         |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Name            | This is only an internal Name to identify your webhook at the overview.                                                                                                                                                                                                                                                         |
+| Trigger         | Trigger can be "Create", "Update", or "Delete". It defines at which action the webhook fires.                                                                                                                                                                                                                                   |
+| Trigger Element | The Trigger Element specifies for which element type the action should apply. For example, Trigger "Update" with Trigger Element "Event" would fire every time, one of your events gets updated.                                                                                                                                |
+| Method          | The Method specifies how the call get send. Can be GET, POST, PUT, PATCH, or DELETE. Mind your security settings at the target system to not block the respective call!                                                                                                                                                         |
+| Payload URL     | The payload URL is the endpoint, the call gets sent to.                                                                                                                                                                                                                                                                         |
+| Header          | At the header input, you can add key-value pairs, which get sent in the header of the call.<br />This is usually helpful for authentication information. Depending on your case, you might also need to add other information to the header - like setting the `Content-Type` explicitly to `application/json` or other things. |
+| Body            | The body input als adds key-value pairs. Adding fields to the body, adds them in addition to the default "element_data".                                                                                                                                                                                                        |
+
+
+## Customize the payload with dynamic values
+
+You can use variables to make custom data dynamic. Next to the "Trigger Element", you find a button, which shows you all available variables for your respective call. Mind that for a DELETE trigger, only the id can be used.
+
+Those variables can be used in the header or body with double curly brackets.
+
+For example, the variable "email", which would hold the user's email address at an RSVP signup, could be added as additional field to the body, setting the key to something like "user-email" and the value to "<span v-pre>{{email}}</span>".
diff --git a/src/de/api/styles.md b/src/de/api/styles.md
deleted file mode 100644
index bb74e2c..0000000
--- a/src/de/api/styles.md
+++ /dev/null
@@ -1,2 +0,0 @@
-
-# Styles API
diff --git a/src/de/automation-integration/webhooks.md b/src/de/automation-integration/webhooks.md
index 290bbb2..8830d0e 100644
--- a/src/de/automation-integration/webhooks.md
+++ b/src/de/automation-integration/webhooks.md
@@ -1,2 +1,37 @@
+# Integrierte Webhooks nutzen
 
-# Making use of the integrated Webhooks
+Du kannst Webhooks verwenden, um einen anderen Dienst oder System zu benachrichtigen, wenn sich etwas bei deinen Add to Calendar PRO Events ändert.
+
+Standardmäßig senden wir alle Daten des Trigger-Elements als JSON-Objekt mit dem Schlüssel "element_data". Du kannst aber auch benutzerdefinierte Felder und Werte ergänzen.
+
+
+## Mögliche Use Cases
+
+* Sende RSVP-Anmeldungen zusätzlich an dein CMS.
+* Tracke die Erstellung von Events in deinem Analytics-Tool, um die interne Nutzung zu überwachen.
+
+
+## Wie es funktioniert
+
+Erstelle einen neuen Webhook in der Anwendung.
+Dort kannst du alle relevanten Parameter festlegen:
+
+
+| Feld            | Wert                                                                                                                                                                                                                                                                                                                                                         |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Name            | Dies ist lediglich der interne Name, um deinen Webhook in Übersichten zu identifizieren.                                                                                                                                                                                                                                                                    |
+| Trigger         | Trigger kann "Neu", "Update" oder "Löschen" sein. Er bestimmt, bei welcher Aktion der Webhook ausgelöst wird.                                                                                                                                                                                                                                              |
+| Trigger-Element | Das Trigger-Element definiert bei welcher Element-Art die Trigger-Aktion greift. Ein Trigger "Update" mit einem Trigger-Element "Event" würde bspw. immer dann ausgelöst werden, wenn eines deiner Events aktualisiert wird.                                                                                                                               |
+| Methode         | Die Methode definiert wie wir die Anfrage an das Dritt-System senden. Der Wert kann GET, POST, PUT, PATCH oder DELETE lauten. Achte darauf, dass die Sicherheits-Einstellungen des Zielsystems die Anfrage nicht blockieren!                                                                                                                                 |
+| Payload-URL     | Die Payload-URL ist der Endpunkt, an den die Anfrage gesendet wird.                                                                                                                                                                                                                                                                                          |
+| Header          | In diese Eingabemaske kannst du Key-Value-Paare hinzufügen, die im Header des Aufrufs gesendet werden.<br />Dies ist für gewöhnlich für die Authentifizierung nötig. Ggf. musst du aber auch andere Informationen in den Header einfügen (abhängig von deinem Zielsystem) - wie einen expliziten `Content-Type` `application/json` oder andere Dinge. |
+| Body            | Hier kannst du ebenfalls Key-Value-Paare hinzufügen. Felder, die hier definiert werden, werden zusätzlich zu dem Standard-Feld "element_data" gesendet.                                                                                                                                                                                                    |
+
+
+## Den Payload mit dynamischen Werten anreichern
+
+Du kannst Variablen verwenden, um benutzerdefinierte Daten dynamisch zu gestalten. Neben dem "Trigger-Element" findest du einen Button, der dir alle verfügbaren Variablen für deinen jeweiligen Aufruf anzeigt. Beachte, dass für einen DELETE-Trigger nur die ID verwendet werden kann.
+
+Diese Variablen können im Header oder Body mit doppelten geschweiften Klammern verwendet werden.
+
+Zum Beispiel kann die Variable "email", die die E-Mail-Adresse des Benutzers bei einer RSVP-Anmeldung enthält, als zusätzliches Feld zum Body hinzugefügt werden, indem der Key auf etwas wie "user-email" und der Wert auf "<span v-pre>{{email}}</span>" festgelegt wird.
diff --git a/src/integration/general.md b/src/integration/general.md
index b2f1000..9c5ad8a 100644
--- a/src/integration/general.md
+++ b/src/integration/general.md
@@ -35,6 +35,12 @@ We automatically generate a proKey for every event you create. You can find it a
 
 When you create an event via our API, you will receive the proKey as response.
 
+::: warning It's client-side only!
+Mind that the button only works on the client-side.
+Therefore, trying to render it on the server (e.g. with SSR or SSG prerendering), might lead to unexpected behavior.
+Depending on your framework, you might want to wrap it into something like `<ClientOnly></ClientOnly>` (Nuxt) or add `use client` to the component (React).
+:::
+
 ## Using it via CDN
 
 Load the script by adding the following script tag to the head section of your website.