ti2-bokun 1.0.2 → 1.0.6

package/README.md

@@ -1,6 +1,6 @@
 # TI2 Bokun Plugin
 
-This is a TourConnect TI2 plugin for integrating with the Bokun booking platform via the OCTO API.
+This is a TourConnect TI2 plugin for integrating with the Bokun booking platform using REST V1 APIs.
 
 ## Prerequisites
 
@@ -31,16 +31,17 @@ npm install
 The plugin uses the following configuration:
 
 ### API Credentials
-The `apiKey` (Bearer token for the OCTO API) is provided via:
+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_apiKey` (already configured in Docker)
+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
 
-- `apiKey`: Bokun API key (Bearer token for OCTO API)
-- `endpoint`: The Bokun OCTO API endpoint (default: https://api.bokun.io/octo/v1; use https://api.bokuntest.com/octo/v1 for testing)
-- `tenant`: Bokun tenant subdomain for booking URL (e.g. `tourconnect-llc`). Enables `privateUrl` in booking information (format: `https://{tenant}.bokun.io/sales/{id}`)
+**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
 
@@ -50,17 +51,33 @@ The plugin supports the following TI2 operations:
 - **Product Search**: Retrieves and translates Bokun products
 - **Availability Search**: Checks product availability and pricing
 - **Availability Calendar**: Returns availability in calendar format
-- **Create Booking**: Creates new bookings in Bokun (OCTO reserve + confirm flow)
-- **Search Booking**: Retrieves booking details by ID or travel date
-- **Cancel Booking**: Not yet implemented for OCTO (see code TODO)
+- **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 uses Bearer token authentication for the Bokun OCTO API. Each request includes:
+The plugin implements Bokun's HMAC-SHA1 signature authentication as described in their API documentation. Each request includes:
 
-- `Authorization: Bearer {apiKey}`
-- `Content-Type: application/json`
-- `Octo-Capabilities: octo/pricing,octo/pickups,octo/cart,octo/offers,octo/questions`
+- `X-Bokun-Date`: Request timestamp in UTC
+- `X-Bokun-AccessKey`: Your access key
+- `X-Bokun-Signature`: HMAC-SHA1 signature of the request
 
 ## Testing
 
@@ -72,18 +89,26 @@ cd ../bbtesting
 docker-compose exec ti2 bash -c "cd /ti2-bokun && npm test"
 ```
 
-Or if you have Node.js installed locally:
+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
-npm test
+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://extranet.bokuntest.com
-- Test API: https://api.bokuntest.com/octo/v1
+- Test Extranet: https://<your tenant>.bokuntest.com
+- Test API: https://api.bokuntest.com
 - Test App Store: https://appstore.bokuntest.com
 
 ## License