@timum/booking 0.6.2 → 0.7.0

package/README.md

@@ -1 +1,613 @@
-Stub
+# timum booking
+
+## Content
+
+- [Basic Usage](#basicUsage)
+  - [In a Script Tag](#inAScriptTag)
+  - [As ESM import](#asEsmImport)
+- [Advanced Usage](#advancedUsage)
+  - [muiTheme](#muiTheme)
+  - [fcConfig](#fullCalendar)
+  - [appConfig](#appConfig)
+  - [How to use Callbacks](#howToUseCallbacks)
+    - [Booking Related](#bookingRelated)
+    - [Cancelation Related](#cancelationRelated)
+    - [Data Fetching Related](#dataFetchingRelated)
+  - [Localisation](#localisation)
+  - [How to Define Fields](#howToDefineFields)
+    - [Anatomy of a Field](#anatomyOfAField)
+  - [An Example](#anExample)
+    - [The Scenario](#theScenario)
+    - [The Implementation](#theImplementation)
+
+### Basic Usage {#basicUsage}
+
+#### In a Script Tag {#inAScriptTag}
+
+Add the following code to your webpage:
+
+```html
+<div id="bookingjs" style="margin: 32px"></div>
+<script type="module">
+  import * as timum from 'https://cdn.jsdelivr.net/npm/@timum/booking@0.6.3/build/timum-booking.js';
+
+  timum.init({ ref: 'booking-widget-demo-resource@timum' });
+</script>
+```
+
+A working fiddle can be found [here](https://jsfiddle.net/timum/3swq1tdy/).
+
+Alternatively, you can add `ref` to your url as a parameter. This allows you to omit `ref` in the javascript portion. Like this:
+
+`https://your.website.nic?ref=<enter resource reference here>`
+
+```html
+<div id="bookingjs" style="margin: 32px"></div>
+<script type="module">
+  import * as timum from 'https://cdn.jsdelivr.net/npm/@timum/booking@0.6.3/build/timum-booking.js';
+
+  timum.init(); //<- no need for the reference here
+</script>
+```
+
+#### As ESM import {#asEsmImport}
+
+1. Add timum-booking to your project with
+   `yarn add @timum/booking`
+   or use npm with
+   `npm install @timum/booking`
+   <br>
+2. Add `<div id="bookingjs" style="margin: 32px"></div>` where you want timum to be displayed (the margin is just a sggestion, not mandatory).
+   <br>
+3. Add the following code to one of your .js files:
+
+```javascript
+import { init } from '@timum/booking';
+
+init({ ref: 'booking-widget-demo-resource@timum' });
+```
+
+A example project can be found [here](https://stackblitz.com/edit/react-8q6r8b?file=src/index.js)
+
+---
+
+### Advanced usage {#advancedUsage}
+
+timum booking has a lot of customisation options.
+
+The init accepts the following arguements in the order listed here.
+The following table gives a rough overview over each.
+
+| Arguments | Description                                                                                        |
+| --------- | -------------------------------------------------------------------------------------------------- |
+| appConfig | object, containing various options like callbacks, localiation, input fields etc.                  |
+| muiTheme  | object, mui theme allowing you to change the look and feel of timum. Requires a professional plan. |
+| fcConfig  | object, only used if you use full calendar as a booking frontend (settable in appConfig).          |
+
+#### muiTheme {#muiTheme}
+
+timum uses mui components for all frontends. The muiTheme object allows global design changes.
+See [here](https://mui.com/) for a general overview. <br> See [here](https://mui.com/material-ui/customization/default-theme/) for theme related documentation.
+
+When you open the file `config.js` in [this](https://stackblitz.com/edit/react-8q6r8b?file=src/index.js) example, you can find an elaborate custom configuration which includes a redesign of the standard timum theme.
+
+#### fcConfig {#fullCalendar}
+
+FullCalendar can be set as one of the frontends in appConfig.
+See [here](https://fullcalendar.io/docs#toc) for a full list of configuration options.
+
+> Note that since fullCalendar isn't mui based, it does not consider the muiTheme object.
+
+#### appConfig {#appConfig}
+
+This object's options directly affect timum's behaviour or allow you to react to it.
+
+<table>
+<tr>
+<th>Property</th>
+<th>Description</th>
+</tr>
+<tr>
+<td>ref</td>
+<td>string, Reference of the resource to show the appointments of. <br><em> This is the only prop that is mandatory.</em><br> Everything else is optional. <br>Can also be a url parameter.</td>
+</tr>
+<tr>
+<td>height</td>
+<td>  string, Height of timum on your page. `500px` is standard.</td>
+</tr>
+<tr>
+<td>channelKey</td>
+<td>string, timum has, as of now, 4 different channels through which you can share your resource's appointments. <br> You can find them in the timum frontend under &lt;resource name&gt; -&gt; Calendar Sharing (Terminbuchung freigeben). <br> Every channel has its own settings allowing you to control whom of your customers can see certain appointments, whether they book directly or create a request first and other settings. <br> Valid values for this attribute are: <br> 
+- RESOURCE_PUBLIC <br> referring to "Public Booking Link" (Öffentlicher Buchungs-Link) <br> 
+- RESOURCE_EXCLUSIVE <br> referring to "Exclusive Booking Access" (Exklusiver Buchungs-Zugang) <br> 
+- RESOURCE_REFERENCE <br> referring to "Embedded booking calendars" (Eingebettete Buchungskalender) <br>
+- CALENDAR_PUBLIC <br> referring to "In all Website Plugin Views and your General Calendar" (In Website-Plugin Ansichten sowie Ihrem Gesamtkalender) <br>RESOURCE_PUBLIC is the default, used if you specify nothing else. <br><br>Can also be a url parameter. </td>
+</tr>
+<tr>
+<td>calendarFrontend</td>
+<td>string, one of `fullCalendar` (that's what `init`'s 3rd parameter is for), `pureListView` or `detailsListView`</td>
+</tr>
+<tr>
+<td>culture</td>
+<td>string, The localisation to use. If not specified the browser language is used. Can also be a url parameter.</td>
+</tr>
+<tr>
+<td>pData</td>
+<td>object, <br> Data indentifying the customer, so that they don't have to input their data again. <br> Works in conjunction with timum and select, supported plaforms like OnOffice, Immosolve etc. <br> Properties: <br> 
+<code>{ platform: string, personId: string }</code> 
+<br> Can also be a url parameter. -&gt; the params are named differently though: pDataPlatform, pDataId</td>
+</tr>
+<tr>
+<td>callbacks</td>
+<td>object, may contain various functions which allow to to run custom code in reaction to certain events. See below for a guide on how to do this. </td>
+</tr>
+<tr>
+<td>fields</td>
+<td>object, You can customise what information is demanded of your customers prior to booking. timum requires certain fields to work and has some optional fields it can parse. Fields other than those supported by timum can be evaluated in a callback (see the callback guide below for further info). All fields (yours too!) support localization and input validation. </td>
+</tr>
+<tr>
+<td>localization</td>
+<td>object. Contains all localization variables and their standard texts. timum nativly supports English and German. Use this to override the standard text and/or add translations for your custom field labels and input validations (see the localisation guide for mor info.)</td>
+</tr>
+</table>
+
+##### How to use callbacks {#howToUseCallbacks}
+
+The callbacks object may contain any of the following functions.
+
+###### Booking related {#bookingRelated}
+
+- `createBookingStarted`
+- `createBookingSuccessfull`
+- `createBookingFailed`
+
+All Booking related callbacks receive a <em>single obejct</em> as argument containing the following properties:
+
+- a `timeslot` looking like this:
+  ```
+     {
+            start: luxon Datetime object. Internal state. "2023-01-27T09:05:00.000Z",
+            end: luxon Datetime object. Internal state. "2023-01-27T09:35:00.000Z",
+            timeslot_uuid: uuid of the booked timeslot. e.g. "82ec5220-9d55-11ed-8617-e4a7a0ca32e8",
+            product_uuid: uuid of the booked product e.g. "92867f70-4836-11e5-bc04-021a52c25043",
+            product_name: string. e.g. "Meeting",
+            resource_name: string. e.g. "Booking Widget DEMO",
+            capacity: number e.g. 1,
+            capacity_left: number e.g. 1,
+            kind: either "models.Bookable" or "models.LotAppointment",
+            untouchedStart: ISO String e.g: "2023-01-27T09:05:00+01:00" as the server sent it,
+            untouchedEnd: ISO String e.g: "2023-01-27T09:35:00+01:00" as the server sent it
+        }
+  ```
+- a `data` looking like this:
+
+```javascript
+ {
+   firstName: 'string',
+   lastName: 'string',
+   email: 'string',
+   agbs: 'bool'
+
+   // plus whatever optional and/or custom fields you yourself has defined.
+   // -> so the makeup of this object changes depending on your settings.
+ }
+
+```
+
+Additionally, `createBookingFailed` and `createBookingSuccessfull` also have a RTKQ `response` object in their respecive argument. See [here](https://redux-toolkit.js.org/rtk-query/usage-with-typescript#type-safe-error-handling) for a reference.
+
+###### Cancelation Related {#cancelationRelated}
+
+- `cancelationStarted`
+- `cancelationSuccessful`
+- `cancelationFailed`
+
+All cancelation related callbacks receive a single obejct as argument containing the same properties as described in [Booking related](#bookingRelated)
+
+Additionally, `cancelationSuccessful` and `cancelationFailed` also have a RTKQ response object in their respecive argument. See here for a reference.
+
+###### Data Fetching Related {#dataFetchingRelated}
+
+In order to display public appointments, resource and calendar information timum sends several requests.
+
+- `fetchingPublicDataSucceeded`
+  Gets passed in a single object looking like this:
+
+  ```javascript
+    {
+      contact: {
+        name: 'string',
+        email: 'string',
+        mobile: 'string',
+        phone: 'string',
+      },
+      resource: {
+        name: 'string', //<- 80 chars, max length of names in timum
+        description: 'string',
+        msgHelpText: 'string',
+      },
+      provider: {
+        name: 'string',
+        description: 'string',
+        isBrandingAllowed: 'boolean',
+      },
+      channel: {
+        bookingProcess: 'string' // One of 'IMMEDIATE' or 'REQUESTED',
+      },
+    }
+  ```
+
+- `fetchingPublicDataFailed`
+  receives a single RTKQ error object. See [here](https://redux-toolkit.js.org/rtk-query/usage-with-typescript#type-safe-error-handling) for a reference.
+  <br>
+- `fetchingProductsSucceeded`
+  Gets passed in a single object looking like this:
+  ```javascript
+  {
+    products: [
+      {
+        description: string,
+        minDuration: number,
+        name: string,
+        uuid
+      }
+      //...
+    ];
+  }
+  ```
+- `fetchingProductsFailed`
+  receives a single RTKQ error object. See [here](https://redux-toolkit.js.org/rtk-query/usage-with-typescript#type-safe-error-handling) for a reference.
+  <br>
+- `fetchingBookablesSucceeded`
+  Gets passed in a single object looking like this:
+  ```javascript
+    {
+      2023-02-06: [ //<- this obviously changes depending on when appointments are available.
+        0: {
+            timeslot_uuid: uuid of the booked timeslot,
+            product_uuid: uuid of the booked product,
+            product_name: string,
+            resource_name: string,
+            capacity: number,
+            capacity_left: number,
+            kind: one of "models.Bookable" or "models.LotAppointment",
+            start: ISO String e.g: "2023-02-06T09:05:00+01:00",
+            end: ISO String e.g: "2023-02-06T09:35:00+01:00"
+        },
+        //... more appointments ...
+      ],
+      //... more dates ...
+    }
+  ```
+  - `fetchingBookablesFailed`
+    receives a single RTKQ error object. See [here](https://redux-toolkit.js.org/rtk-query/usage-with-typescript#type-safe-error-handling) for a reference.
+    <br>
+
+##### Localisation {#localisation}
+
+timum booking has the ability to change all of its text. It comes with English and German pre-installed, but you can add additional translations as well. You can also change the text for these languages to your preference. You don't have to redefine the entire localization object; you can just add or change the specific texts you want. Any missing texts will be taken from the default.
+The code snippet provided shows the complete localization object and the standard text for both English and German. For each language, it includes text for different parts of the booking process such as product selection, appointment booking, appointment request, appointment cancellation, form fields, and more.
+
+```javascript
+localization: {
+  de: {
+    product_selection_headline: 'Terminart wählen',
+    booked_successfully_header: 'Termin gebucht',
+    booked_successfully_message:
+      'Sie erhalten eine E-Mail mit den Termindetails an {{mail}}',
+    requested_successfully_header: 'Termin angefragt',
+    requested_successfully_message:
+      'Sie erhalten eine E-Mail mit den Termindetails an {{mail}}. Sie werden unter der gleichen Adresse benachrichtigt, sobald Ihre Anfrage bearbeitet wurde.',
+    submit_button_book: 'Buchen',
+    submit_button_request: 'Verbindlich Anfragen',
+
+    noEventsMessage:
+      'Zur Zeit sind leider keine buchbaren Termine verfügbar.',
+    appoinment_at_capacity: 'vollständig ausgebucht',
+    add_to_calendar_btn: 'Zu Kalender hinzufügen',
+    until_reservation_expiration:
+      '{{expiration}} bis zum Ablauf der Reservierung',
+    reservation_expired: 'Reservierung abgelaufen.',
+    identified_customer_hint:
+      'Sie wurden mit persönlichem Link eingeladen und können direkt Ihren Termin buchen.',
+    reservation_failed: {
+      title: 'Hohe Nachfrage',
+      mesage:
+        'Dieser Termin wurde gerade durch jemanden reserviert. Bitte wählen' +
+        'Sie einen anderen Termin. Oder schauen Sie später noch einmal, ob' +
+        'ein Termin frei wird.',
+    },
+    cancellation: {
+      cancelation_successfull_message: 'Termin erfolgreich abgesagt',
+      cancellable_appointment_highlight: 'Mein Termin',
+      submit_button_cancel: 'Absagen',
+      cancel_appointment_header: 'Ihr Termin',
+      message_label: 'Nachricht zur Terminabsage',
+    },
+    validation: {
+      field_required: 'Notwendig',
+      privacy_field_required:
+        'Sie müssen die Datenschutzbestimmungen akzeptieren bevor Sie buchen können.',
+      email_field_must_be_valid: 'Geben Sie eine valide E-Mail Adresse ein',
+    },
+    fields: {
+      firstName: 'Vorname',
+      lastName: 'Nachname',
+      name: 'Name',
+      email: 'E-Mail',
+      mobile: 'Mobil',
+      message: 'Ihre Nachricht',
+      accept_timum_privacy:
+        'Datenschutzbestimmungen gelesen und akzeptiert',
+    },
+  },
+  // the same for english.
+  en: {
+    product_selection_headline: 'Choose Product',
+    booked_successfully_header: 'Appoinment Booked',
+    booked_successfully_message:
+      'You will receive an email with appointment details to {{mail}}',
+    requested_successfully_header: 'Appointment Requested',
+    requested_successfully_message:
+      'You will receive an email with appointment details to {{mail}}. You will be notified at the same address once your request has been processed.',
+    submit_button_book: 'Book',
+    submit_button_request: 'Request',
+
+    noEventsMessage:
+      'Unfortunately, there are no bookable dates available at the moment.',
+    appoinment_at_capacity: 'fully booked',
+    add_to_calendar_btn: 'Add to Calendar',
+    until_reservation_expiration:
+      '{{expiration}} until reservation expiration.',
+    reservation_expired: 'Reservation expired.',
+    identified_customer_hint:
+      'You have been invited with a personal link and can book your appointment directly.',
+    reservation_failed: {
+      title: 'High Demand',
+      mesage:
+        'This appointment has just been reserved by someone. Please choose another appointment. Or check back later to see if an appointment becomes available.',
+    },
+    cancellation: {
+      cancelation_successfull_message: 'Appointment canceled sucessfully.',
+      cancellable_appointment_highlight: 'My Appointment',
+      submit_button_cancel: 'Cancel',
+      cancel_appointment_header: 'Your Appointment',
+      message_label: 'You may enter a reason here.',
+    },
+    validation: {
+      field_required: 'Required',
+      privacy_field_required:
+        'You must accept the privacy policy prior to booking.',
+      email_field_must_be_valid: 'Enter a valid email address',
+    },
+    fields: {
+      firstName: 'First name',
+      lastName: 'Last name',
+      name: 'name',
+      email: 'E-mail',
+      mobile: 'Mobile',
+      message: 'Your Message',
+      accept_timum_privacy: '<0>Privacy policy</0> read and accepted.',
+    },
+  },
+},
+```
+
+##### How to define fields {#howToDefineFields}
+
+You can customize the information required from customers before booking by defining fields. The minimum required fields for timum are firstName, lastName, email, and agbs. By default, timum also requests mobile and message fields, but you can add your own fields as well.
+
+Fields, including custom ones, support validation and localization.
+Validation is realized using the yup library, which is included with timum. You can import it using the following code:
+
+```javascript
+import { yup } from '@timum/booking';
+```
+
+Localization is achieved by using the title property in the field definition. You can specify a translation key and add the corresponding translation to the localization object. The same process can be applied to custom field validations.
+
+The standard configuration can be overridden except for the aforementioned fields. The following is the standard configuration:
+
+```javascript
+  fields: {
+    firstName: {
+      title: 'fields.firstName',
+      validation: yup.string().required('validation.field_required'), // <- compare with key in 'localization'
+    },
+    lastName: {
+      title: 'fields.lastName',
+      validation: yup.string().required('validation.field_required'),
+    },
+    email: {
+      title: 'fields.email',
+      format: 'email',
+      type: 'text',
+      validation: yup
+        .string()
+        .email('validation.email_field_must_be_valid')
+        .required('validation.field_required'),
+    },
+    mobile: {
+      title: 'fields.mobile',
+      type: 'phoneNumber',
+      isRequired: false,
+      // validation: is in built and ignored
+    },
+    message: {
+      title: 'fields.message',
+      type: 'textarea',
+      validation: yup.string().max(1024),
+      limit: 1024,
+    },
+    agbs: {
+      title: 'fields.accept_timum_privacy',
+      type: 'checkbox',
+      validation: yup
+        .boolean()
+        .required('validation.field_required')
+        .test(
+          'privacyAccepted',
+          'validation.privacy_field_required',
+          (value) => value === true
+        ),
+    },
+  },
+```
+
+###### Anatomy of a field {#anatomyOfAField}
+
+```
+  <fieldName> : {
+      title: string or JSXElement;
+      validation: yup based validation. See https://github.com/jquense/yup. Re-exported and accessible via timum.yup
+      type: string; either 'text' (default), 'phoneNumber', 'textarea', 'checkbox' or 'select',
+      prefilled: string; value a fiels is initiated with. Not that for fields of type 'select' you must use the 'key' of on of it's options.
+  }
+```
+
+Depending on the type there are additional properties you can/must specify:
+
+- Type `text`:
+
+  - `format`: string; the native input field's 'type' (e.g. 'email', 'number', etc.).
+
+- Type `phoneNumber`:
+
+  - does NOT support `validation`. Phone number validation is complex, so timum handles it for you.
+    This does mean that field validation localisation is currently not supported for fields of this type.
+    This will be fixed in a future update.
+  - isRequired: boolean; if true, this field must be filled with a valid number
+
+- Type `textArea`:
+
+  - limit: number; sets the maximum number of characters customers can enter.
+
+- Type `checkbox`:
+  - no special properties.
+
+Type `select`:
+
+- options: array of objects with structure { title: string, key: string }. The title is displayed and the key is passed in the data object to callbacks.
+
+#### An Example {#anExample}
+
+Here is an example Tying all of the aforementioned concepts together.
+
+##### The Scenario {#theScenario}
+
+For whatever reason it is important to know the gender of customers.
+On the other side the optional fields `mobile` and `message` aren't important for you and you wish to remove them.
+This new gender field must be filled, therefore a validation is required.
+Both the title of the field and it's validations must be localized.
+
+##### The Implementation {#theImplementation}
+
+This is the base configuration. As it is it uses the standard field configuration shown in [How to define fields](#howToDefineFields).
+
+```html
+<div id="bookingjs" style="margin: 32px"></div>
+<script type="module">
+  import * as timum from 'https://cdn.jsdelivr.net/npm/@timum/booking@0.6.3/build/timum-booking.js';
+
+  timum.init({ ref: 'booking-widget-demo-resource@timum' });
+</script>
+```
+
+Let's add the necessary changes:
+
+```html
+<div id="bookingjs" style="margin: 32px"></div>
+<script type="module">
+  import * as timum from 'https://cdn.jsdelivr.net/npm/@timum/booking@0.6.3/build/timum-booking.js';
+
+  timum.init(
+  {
+    ref: 'booking-widget-demo-resource@timum',
+    fields: {
+      // set these fields to undefined explicitly in order to remove them
+      message: undefined,
+      mobile: undefined,
+      firstName: {
+        // index defines the order in which the fields get displayed
+        index: 0,
+        title: 'fields.firstName',
+        validation: yup.string().required('validation.field_required'), // <- compare with key in localisation
+      },
+      lastName: {
+        index: 1,
+        title: 'fields.lastName',
+        validation: yup.string().required('validation.field_required'),
+      },
+      email: {
+        index: 2,
+        title: 'fields.email',
+        format: 'email',
+        type: 'text',
+        validation: yup
+          .string()
+          .email('validation.email_field_must_be_valid')
+          .required('validation.field_required'),
+      },
+      gender: {
+        index: 3,
+        // new language key
+        title: 'fields.gender.title',
+        // best for a limited number of predefined choices
+        type: 'select',
+        // could use 'validation.field_required' but
+        // for this example let's create a new  key
+        validation: yup.string().required('validation.gender_field_required'),
+        options: [
+          { key: 'm', title: 'fields.gender.male' },
+          { key: 'w', title: 'fields.gender.female' },
+          { key: 'd', title: 'fields.gender.other' },
+        ],
+      },
+      agbs: {
+        index: 4,
+        title: 'Datenschutzbestimmungen gelesen und akzeptiert.',
+        type: 'checkbox',
+        validation: yup
+          .boolean()
+          .required('validation.field_required')
+          .test(
+            'privacyAccepted',
+            'validation.privacy_field_required',
+            (value) => value === true
+          ),
+      },
+    }
+
+    // now we need to add the new translation keys and their translations.
+
+    localization: {
+      de: {
+        validation: {
+          gender_field_required: 'Bitte wählen.'
+        },
+        fields: {
+          gender: {
+            title: 'Geschlecht',
+            male: 'Männlich',
+            female: 'Weiblich',
+            other: 'Divers'
+          },
+        }
+      },
+      en: {
+          validation: {
+          gender_field_required: 'Please select an option.'
+        },
+          fields: {
+            gender: {
+              title: 'Gender',
+              male: 'Male',
+              female: 'Female',
+              other: 'Others'
+            },
+        }
+      }
+    }
+  });
+</script>
+```