# TI2 Bokun Plugin

This is a TourConnect TI2 plugin for integrating with the Bokun booking platform using REST V1 APIs.

## Prerequisites

This plugin is designed to work with the TourConnect TI2 Docker environment. Make sure you have:
- Docker and Docker Compose installed
- The TI2 container running from `../bbtesting`

## Installation

The plugin is automatically mounted into the TI2 container via the docker-compose-ti2.yml configuration.

To install dependencies within the TI2 container:

```bash
# From the bbtesting directory
cd ../bbtesting
docker-compose exec ti2 bash -c "cd /ti2-bokun && npm install"
```

Or if you have Node.js installed locally:

```bash
npm install
```

## Configuration

The plugin uses the following configuration:

### API Credentials
The `accessKey` and `secretKey` are provided via:
1. **TI2 instantiation** - Passed when creating the plugin instance (production use)
2. **Environment variables** - For testing: `ti2_bokun_accesskey` and `ti2_bokun_secretkey` (already configured in Docker)

### User Configuration Parameters
The following parameters are configured by the user through TI2:
- `endpoint`: The Bokun API endpoint (default: https://api.bokun.io, use https://api.bokuntest.com for testing)
- `tenant`: Your Bokun vendor **subdomain** (the hostname prefix before `.bokun.io` / `.bokuntest.com`). Used with `endpoint` to build `publicUrl` and `privateUrl` when the API does not return them (same idea as ti2-rezdy deriving URLs from the configured API host).
- `testMode`: Boolean flag to use test environment

**Booking URLs:** Both`publicUrl` / `privateUrl` (or related fields) are derived from `endpoint` + `tenant`: customer `publicUrl` as `https://{tenant}.{domain}/sales/{confirmationCode}`, and `privateUrl` as `https://{tenant}.{domain}/booking/{confirmationCode}` (same subdomain as your Bokun vendor site). Adjust paths if Bokun changes routing.

## Features

The plugin supports the following TI2 operations:

- **Token Validation**: Validates Bokun API credentials
- **Product Search**: Retrieves and translates Bokun products
- **Availability Search**: Checks product availability and pricing
- **Availability Calendar**: Returns availability in calendar format
- **Pickup Points**: Retrieves pickup locations for products
- **Create Booking**: Creates new bookings in Bokun
- **Cancel Booking**: Cancels existing bookings
- **Search Booking**: Retrieves booking details

## API Compliance

This plugin uses the [Bókun REST v1 API](https://api-docs.bokun.dev/rest-v1) ([OpenAPI spec](https://api-docs.bokun.dev/rest-v1.yaml)). Endpoints used:

| TI2 operation   | Method | Endpoint | Spec |
|-----------------|--------|----------|------|
| Token validation | `POST` | `/activity.json/search` | ActivityQuery body: `{ page, pageSize }` |
| Product search   | `POST` | `/activity.json/search` | ActivityQuery body: `{ page, pageSize, currency? }` |
| Product by ID    | `GET`  | `/activity.json/{id}` | Query: `currency?`, `lang?` |
| Availability     | `GET`  | `/activity.json/{id}/availabilities` | Query: `start` (required), `end` (required), `currency?`, `includeSoldOut?` |
| Pickup places    | `GET`  | `/activity.json/{id}/pickup-places` | — |
| Create booking   | `POST` | `/checkout.json/submit` then `/checkout.json/confirm-reserved/{confirmationCode}` | Checkout submit + confirm flow |
| Cancel booking   | `POST` | `/booking.json/cancel-booking/{confirmationCode}` | Body: `{ note?, notify? }` |
| Get booking      | `GET`  | `/booking.json/booking/{confirmationCode}` | Query: `currency?`, `lang?` |

## API Authentication

The plugin implements Bokun's HMAC-SHA1 signature authentication as described in their API documentation. Each request includes:

- `X-Bokun-Date`: Request timestamp in UTC
- `X-Bokun-AccessKey`: Your access key
- `X-Bokun-Signature`: HMAC-SHA1 signature of the request

## Testing

To run tests within the TI2 container:

```bash
# From the bbtesting directory
cd ../bbtesting
docker-compose exec ti2 bash -c "cd /ti2-bokun && npm test"
```

Or if you have Node.js installed locally in this plugin directory:

```bash
npx jest "index.test.js" --config='{}'
```

To run only the core operations covered in current regression tests:

```bash
npx jest "index.test.js" --config='{}' --runInBand --testNamePattern="searchAvailability|createBooking|cancelBooking|searchBooking|validateToken|searchProducts|availabilityCalendar"
```

Note: some negative-path tests intentionally exercise error handling (for example invalid token, malformed availability key, or booking lookup failures). Those tests may print `console.error` lines while still passing.

## Environment Setup

For development and testing, you can use Bokun's test environment:

- Test Extranet: https://<your tenant>.bokuntest.com
- Test API: https://api.bokuntest.com
- Test App Store: https://appstore.bokuntest.com

## License

GPL-3.0