# Tripfusion JavaScript SDK

## Installation

Add the following script to the `<head>` section on all pages where the widget will be used. Replace `<client>` and `<propertyId>` with the appropriate values.

```html
<script
    id="tripfusion-sdk"
    src="https://cdn.jsdelivr.net/npm/@vacayou/tripfusion-js-sdk@latest?client=<client>&propertyId=<propertyId>"
></script>
```

## Usage

The booking widget can be controlled both via JavaScript function calls and via html-links.

**Using the widget with JS functions**  
To display the widget, you need to add the `book` function as an event handler, for example:

```html
<button onClick="book({...config})">Book Now</button>
```

The widget configuration is done using the optional [parameters](#configuration-options).
To hide the widget, you need to call the `closeWidget()` function.

**Using the widget with HTML links**  
To trigger the booking widget, simply add the following parameters to any HTML link on the page:

```
https://<link>/?tripfusion=true[&options=...]
```

The widget configuration is done by passing additional [parameters](#configuration-options) in the link (parameter names are the same as those used when calling the JS `book()` function, all parameters should be separated by `&` symbol), for example:

-   Standard booking:

```
https://website.com/?tripfusion=true
```

-   Booking with an offer:

```
https://website.com/?tripfusion=true&offerId=<offer-id>
```

-   Experience booking mode with predefined check-in and check-out dates, number of adult guests, and children (children's ages separated by commas):

```
https://website.com/?tripfusion=true&checkin=2022-10-10&checkout=2022-10-12&adults=2&children=5,7
```

## Configuration options

| Parameter  | Required             | Description                                                                                                                                                                                                                                                                                                                     |
| ---------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| client          | yes (in script tag) | You can override the default client ID that normally should be set in `<script>` tag.                                                                                                                                                          |
| propertyId      | one of these is required | Numeric property ID. Produces iframe URL `/{client}/{propertyId}`.                                                                                                                                                                            |
| propertySlug    | one of these is required | URL-safe property slug. Produces iframe URL `/{client}/{propertySlug}`. Use when you have the slug but not the ID.                                                                                                                            |
| landingPagePath | one of these is required | Offer landing-page slug. Produces iframe URL `/{client}/offers/{landingPagePath}`.                                                                                                                                                            |
| landingPageId   | one of these is required | Numeric landing-page ID. Produces iframe URL `/{client}/offers/{landingPageId}`. Use when you have the ID but not the slug.                                                                                                                   |
| mode            | no                  | Booking mode: `normal` or `append` (for adding items to an existing booking).                                                                                                                                                                  |
| bookingId  | yes (in append mode) | Existing booking ID to add items to. <br> This parameter is used only when `mode` is `append`.                                                                                                                                                                                                                                  |
| offerId    | no                   | Triggers the booking widget with the settings of the specified offer.                                                                                                                                                                                                                                                           |
| checkIn    | no                   | Check-in date. Format: `YYYY-MM-DD` <br> This parameter is used only when the property is configured for experience-only mode.                                                                                                                                                                                                  |
| checkOut   | no                   | Check-out date. Format: `YYYY-MM-DD` <br> This parameter is used only when the property is configured for experience-only mode.                                                                                                                                                                                                 |
| adults     | no                   | Adult guests count. <br> This parameter is used only when the property is configured for experience-only mode.                                                                                                                                                                                                                  |
| children   | no                   | Children's ages. <br> This parameter is used only when the property is configured for experience-only mode. <br> When using the JS function, children's ages should be passed as an array, for example: `children: [5,7]`. <br> When using an HTML link, children's ages are separated by commas, for example: `&children=5,7`. |
| pk         | required when the partner origin is CSP-allowlisted (optional otherwise) | Embed public key, format `pk_(live\|test)_[A-Za-z0-9]{32}`. Obtained from the TripFusion admin Developers page. Keys are in-memory only and never persisted to sessionStorage. See the [partner embed security spec](../docs/2026-06-20-partner-embed-security-design.md) for details. SDK ≥ 1.56 required. |

Precedence when multiple entity params are set: `landingPageId` > `landingPagePath` > `propertySlug` > `propertyId`. Pass only one — the rest are no-ops.

## PostMessage handshake

SDK ≥ 1.56 participates in a secure handshake with the embedded checkout iframe. The flow:

1. After loading, the checkout iframe posts a `tripfusion-embed-handshake-request` message to the parent window.
2. The SDK verifies the message came from the expected iframe (`event.source === iframe.contentWindow`) and that the origin matches a TripFusion checkout domain (`checkout.tripfusion.com`, `develop.checkout.tripfusion.com`, or `staging.checkout.tripfusion.com`). When the SDK is explicitly running in local env (`env=local`), `localhost`/`127.0.0.1` origins are also allowed for local development — production scripts use the default env, so this branch is dead in production and never weakens it. Non-allowed origins are discarded immediately.
3. The SDK replies with a `tripfusion-embed-handshake-response` message containing the embed key (`{ type, key }`), sent to `event.origin` (never `"*"`).
4. The iframe calls `/api/embed/verify` with the key and the parent origin. On success, the session cookie is set and booking proceeds.

All non-TripFusion `postMessage` events (e.g. from third-party scripts on the partner page) are silently ignored by the origin guard at the top of the handler. This closes the spoofed-message attack surface described in §7 of the partner embed security design doc.
