wp-bnb/README.md

# WP BnB Management

A comprehensive Bed & Breakfast management system for WordPress. Manage buildings, rooms, bookings, and guests all within your WordPress admin.

## Description

WP BnB Management enables WordPress to act as a full management system for B&B hosts. It handles multiple buildings with multiple rooms each, bookings, and guest data required for room rentals.

### Key Features

- **Multi-Property Support**: Manage multiple buildings, each with multiple rooms
- **Flexible Pricing**: Configure short-term (nights), mid-term (weeks), and long-term (months) pricing
- **Seasonal Pricing**: Set price modifiers for high/low seasons
- **Booking Management**: Track reservations from inquiry to checkout
- **Guest Management**: Store guest information securely with GDPR compliance
- **Data Encryption**: Sensitive guest data (ID/passport) encrypted at rest
- **Additional Services**: Offer extras like breakfast, parking, or tours
- **Frontend Integration**: Gutenberg blocks, widgets, and shortcodes
- **Auto-Updates**: Automatic update checks and installation from license server
- **Development Mode**: License bypass for local development environments
- **Contact Form 7 Integration**: Accept booking requests and inquiries through CF7 forms
- **Dashboard**: Comprehensive admin dashboard with statistics and charts
- **Reports**: Detailed reports with CSV and PDF export
- **Prometheus Metrics**: Expose operational metrics for monitoring with Grafana

### Requirements

- WordPress 6.0 or higher
- PHP 8.3 or higher
- Valid license key
- Contact Form 7 (optional, for booking forms)

## Installation

1. Download the latest release from the [releases page](https://src.bundespruefstelle.ch/magdev/wp-bnb/releases)
2. Upload the plugin to your `/wp-content/plugins/` directory
3. Activate the plugin through the 'Plugins' menu in WordPress
4. Go to **WP BnB → Settings → License** to enter your license key
5. Configure your business settings under **WP BnB → Settings**

## Configuration

### License Activation

1. Navigate to **WP BnB → Settings → License**
2. Enter your License Server URL
3. Enter your License Key (from purchase confirmation)
4. Enter the Server Secret (from purchase confirmation)
5. Click **Activate License**

### General Settings

- **Business Name**: Your B&B business name
- **Currency**: Select your preferred currency (CHF, EUR, USD, GBP)
- **Business Address**: Street, city, postal code, country
- **Contact Information**: Email, phone, website
- **Social Media**: Facebook, Instagram, X (Twitter), LinkedIn, TripAdvisor

### Update Settings

- **Update Notifications**: Enable/disable update notifications in WordPress
- **Automatic Updates**: Enable/disable automatic plugin updates
- **Check Frequency**: How often to check for updates (1-168 hours)

### Development Mode

The plugin automatically detects local development environments and bypasses license validation. Supported environments:

- localhost, 127.0.0.1, ::1
- Domains ending in .local, .test, .localhost, .dev, .ddev.site
- Private IP ranges (10.x.x.x, 172.16-31.x.x, 192.168.x.x)

## Usage

### Managing Buildings

1. Go to **WP BnB → Buildings**
2. Click **Add New**
3. Enter building details (name, address, description)
4. Add featured image
5. Publish

### Managing Rooms

1. Go to **WP BnB → Rooms**
2. Click **Add New**
3. Select the parent building
4. Configure room details and pricing
5. Add amenities and room type
6. Publish

### Managing Bookings

1. Go to **WP BnB → Bookings**
2. View and manage all reservations
3. Update booking status as guests progress

### Managing Guests

1. Go to **WP BnB → Guests**
2. View guest records and booking history
3. Manage guest information

### Dashboard

The dashboard (**WP BnB → Dashboard**) provides an at-a-glance overview of your B&B operations:

**Statistics Cards:**

- **Occupancy Rate** - Current percentage of rooms occupied with trend indicator
- **Monthly Revenue** - This month's revenue with comparison to previous month
- **Total Bookings** - Active bookings count with status breakdown
- **Total Guests** - Guest count with new guests this month

**Today's Activity:**

- Check-ins scheduled for today with guest names and room assignments
- Check-outs scheduled for today
- Quick links to manage each booking

**Upcoming Bookings:**

- Next 7 days of arrivals
- Guest name, room, dates, and booking status
- Direct links to booking details

**Quick Actions:**

- New Booking - Create a booking directly
- New Guest - Add a guest record
- View Calendar - Open the availability calendar
- View Reports - Access detailed reports

**Trend Charts:**

- 30-day occupancy trend line chart
- 6-month revenue bar chart

### Reports

Access detailed reports at **WP BnB → Reports**. All reports support date range filtering and export.

**Occupancy Report:**

- Overall occupancy percentage for the selected period
- Breakdown by room showing nights booked, available, and occupancy rate
- Visual progress bars for easy comparison
- Total nights booked vs. available across all rooms

**Revenue Report:**

- Total revenue for the selected period
- Revenue breakdown by room
- Revenue breakdown by pricing tier (short-term, mid-term, long-term)
- Revenue from additional services
- Average booking value

**Guest Statistics:**

- Total guests and new guests in period
- Repeat guest rate (guests with 2+ bookings)
- Top guests by total spending
- Guest nationality distribution
- Average spending per guest

**Export Options:**

- **CSV Export** - Download report data as spreadsheet-compatible CSV
- **PDF Export** - Generate formatted PDF reports for printing or archiving

**Date Filters:**

- This Month (default)
- Last Month
- This Year
- Custom date range

## Shortcodes

Display buildings and rooms on your site using shortcodes:

```txt
[bnb_buildings]                    - List all buildings (grid/list layout)
[bnb_rooms building="123"]         - List rooms, optionally filtered by building
[bnb_room_search]                  - Interactive room search form
[bnb_building id="123"]            - Display a single building
[bnb_room id="456"]                - Display a single room with availability
```

### Shortcode Attributes

**`[bnb_buildings]`** and **`[bnb_rooms]`**:

- `layout` - "grid" or "list" (default: grid)
- `columns` - 1-4 columns (default: 3)
- `limit` - Number of items (default: 12)
- `orderby` - title, date, price, capacity (default: title)
- `order` - ASC or DESC (default: ASC)

**`[bnb_rooms]`** additional attributes:

- `building` - Building ID to filter by
- `room_type` - Room type slug to filter by
- `amenities` - Comma-separated amenity slugs

## Gutenberg Blocks

The following blocks are available in the block editor:

- **Building** - Display a single building with details
- **Room** - Display a single room with availability form
- **Room Search** - Interactive search form with filters
- **Buildings List** - Display buildings grid/list
- **Rooms List** - Display rooms grid/list with filters

## Widgets

Available sidebar widgets:

- **Similar Rooms** - Show rooms from same building or room type
- **Building Rooms** - List all rooms in a building
- **Availability Calendar** - Mini calendar showing booking status

## Contact Form 7 Integration

The plugin integrates with Contact Form 7 to accept booking requests and inquiries. Custom form tags are provided for room selection, date pickers, and guest counts.

### Custom Form Tags

Use these tags in your CF7 forms:

- `[bnb_building_select name]` - Building dropdown (optional filter for rooms)
- `[bnb_room_select* name]` - Room dropdown with capacity data
- `[bnb_date_checkin* name]` - Check-in date picker
- `[bnb_date_checkout* name]` - Check-out date picker
- `[bnb_guests* name]` - Guest count input

### Tag Options

**`[bnb_building_select]`**:

- `first_as_label:"text"` - Placeholder text (default: "All Locations")

**`[bnb_room_select]`**:

- `building_field:"name"` - Link to building field for filtering
- `first_as_label:"text"` - Placeholder text (default: "Select Room")

**`[bnb_guests]`**:

- `min:N` - Minimum guests (default: 1)
- `max:N` - Maximum guests (default: 10)
- `default:N` - Default value (default: 1)

### Example Booking Form

```txt
<div class="wp-bnb-booking-form">
<h3>Book Your Stay</h3>

<div class="wp-bnb-form-row">
[bnb_building_select building first_as_label:"All Locations"]
</div>

<div class="wp-bnb-form-row">
[bnb_room_select* room building_field:"building" first_as_label:"Select a Room"]
</div>

<div class="wp-bnb-form-row-2col">
<div class="wp-bnb-form-field">
<label>Check-in</label>
[bnb_date_checkin* check_in]
</div>
<div class="wp-bnb-form-field">
<label>Check-out</label>
[bnb_date_checkout* check_out]
</div>
</div>

<div class="wp-bnb-availability-status"></div>

<div class="wp-bnb-form-row">
<label>Number of Guests</label>
[bnb_guests* guests min:1 max:10 default:2]
</div>

<div class="wp-bnb-price-display"></div>

<h4>Your Information</h4>

<div class="wp-bnb-form-row-2col">
<div class="wp-bnb-form-field">
<label>First Name</label>
[text* first_name]
</div>
<div class="wp-bnb-form-field">
<label>Last Name</label>
[text* last_name]
</div>
</div>

<div class="wp-bnb-form-row">
<label>Email</label>
[email* your_email]
</div>

<div class="wp-bnb-form-row">
<label>Phone</label>
[tel your_phone]
</div>

<div class="wp-bnb-form-row">
<label>Message</label>
[textarea your_message]
</div>

[submit "Request Booking"]
</div>
```

### Example Inquiry Form

For room-specific inquiries, add the `wp-bnb-inquiry-form` class:

```txt
<div class="wp-bnb-inquiry-form">
<h3>Inquire About This Room</h3>

[hidden room default:123]

<div class="wp-bnb-form-row">
<label>Your Name</label>
[text* your_name]
</div>

<div class="wp-bnb-form-row">
<label>Email</label>
[email* your_email]
</div>

<div class="wp-bnb-form-row">
<label>Your Question</label>
[textarea* your_message]
</div>

[submit "Send Inquiry"]
</div>
```

### Form Features

- **Availability Checking**: Real-time AJAX validation shows room availability
- **Price Display**: Estimated total calculated and displayed automatically
- **Room Filtering**: Rooms filter by building selection
- **Date Validation**: Check-out must be after check-in, no past dates
- **Capacity Validation**: Guest count validated against room capacity
- **Automatic Booking**: Booking record created with "pending" status on submission
- **Guest Linking**: Guest records created or linked by email address

### Custom Mail Tags

Use these in your CF7 mail templates:

- `[_bnb_room_name]` - Room title
- `[_bnb_building_name]` - Building name
- `[_bnb_calculated_price]` - Formatted price
- `[_bnb_nights]` - Number of nights
- `[_bnb_booking_reference]` - Booking reference (after creation)

## Hooks and Filters

Developers can customize behavior using these hooks:

```php
// Modify price calculation
add_filter( 'wp_bnb_calculate_price', function( $price, $room_id, $dates ) {
    // Custom pricing logic
    return $price;
}, 10, 3 );

// Before booking creation
add_action( 'wp_bnb_before_booking_create', function( $booking_data ) {
    // Custom validation or logging
} );
```

## Prometheus Metrics

The plugin integrates with [WP Prometheus](https://src.bundespruefstelle.ch/magdev/wp-prometheus) to expose operational metrics for monitoring with Prometheus and Grafana.

### Enabling Metrics

1. Install and activate the WP Prometheus plugin
2. Navigate to **WP BnB → Settings → Metrics**
3. Enable "Expose BnB metrics via Prometheus"
4. Metrics will be available at your site's `/metrics/` endpoint

### Available Metrics

**Inventory Metrics:**

- `wp_bnb_buildings_total` - Total number of buildings
- `wp_bnb_rooms_total{status}` - Rooms by status (available, occupied, maintenance, inactive)
- `wp_bnb_services_total{status}` - Services by status (active, inactive)
- `wp_bnb_total_capacity_beds` - Total bed capacity across all rooms

**Booking Metrics:**

- `wp_bnb_bookings_total{status}` - Bookings by status (pending, confirmed, checked_in, checked_out, cancelled)
- `wp_bnb_checkins_today` - Check-ins scheduled for today
- `wp_bnb_checkouts_today` - Check-outs scheduled for today
- `wp_bnb_bookings_upcoming_7days` - Bookings starting in next 7 days
- `wp_bnb_booking_avg_duration_nights` - Average booking duration

**Occupancy Metrics:**

- `wp_bnb_occupancy_rate_current` - Current room occupancy rate (percentage)
- `wp_bnb_occupancy_rate_this_month` - Monthly occupancy rate (percentage)
- `wp_bnb_rooms_currently_occupied` - Rooms currently occupied

**Revenue Metrics:**

- `wp_bnb_revenue_this_month{currency}` - Revenue for current month
- `wp_bnb_revenue_ytd{currency}` - Revenue year to date
- `wp_bnb_booking_avg_value{currency}` - Average booking value
- `wp_bnb_services_revenue_this_month{currency}` - Services revenue this month

**Guest Metrics:**

- `wp_bnb_guests_total` - Total registered guests
- `wp_bnb_guests_by_status{status}` - Guests by status (active, blocked, vip)
- `wp_bnb_guests_repeat` - Guests with more than one booking
- `wp_bnb_guests_new_this_month` - New guests this month

### Grafana Dashboard

A pre-configured Grafana dashboard is included at `assets/grafana/wp-bnb-dashboard.json`. If WP Prometheus is installed, the dashboard is automatically registered and available for export.

The dashboard includes:

- Occupancy gauges with color-coded thresholds
- Bookings, rooms, and guests pie charts by status
- Revenue and guest statistics panels
- Today's check-ins/check-outs
- Trend indicators

## REST API

The plugin provides a comprehensive REST API for integration with external applications, mobile apps, and third-party services.

### Enabling the API

1. Navigate to **WP BnB → Settings → API**
2. In the **General** subtab, enable "Enable REST API"
3. Optionally enable rate limiting for protection against abuse
4. Configure rate limits in the **Rate Limits** subtab
5. View all available endpoints in the **Endpoints** subtab

### Base URL

All API endpoints are prefixed with:

```txt
https://your-site.com/wp-json/wp-bnb/v1/
```

### Authentication

**Public endpoints** (room listings, availability checks) require no authentication.

**Admin endpoints** (booking management, guest data) require authentication via:

- **Cookie + Nonce**: For same-domain JavaScript requests
- **Application Passwords**: For external applications (WordPress 5.6+, recommended)

To create an Application Password:

1. Go to **Users → Profile**
2. Scroll to "Application Passwords"
3. Enter a name and click "Add New Application Password"
4. Use the generated password with HTTP Basic Auth

```bash
curl -u "username:app-password" https://site.com/wp-json/wp-bnb/v1/bookings
```

### Public Endpoints

| Method | Endpoint | Description |
| ------ | -------- | ----------- |
| GET | `/buildings` | List all buildings |
| GET | `/buildings/{id}` | Get building details |
| GET | `/buildings/{id}/rooms` | Get rooms in a building |
| GET | `/rooms` | List/search rooms |
| GET | `/rooms/{id}` | Get room details |
| GET | `/rooms/{id}/availability` | Check room availability |
| GET | `/rooms/{id}/calendar` | Get monthly calendar data |
| POST | `/availability/search` | Search available rooms |
| GET | `/services` | List all services |
| GET | `/services/{id}` | Get service details |
| POST | `/pricing/calculate` | Calculate booking price |
| POST | `/bookings` | Create a new booking (pending status) |

### Admin Endpoints

| Method | Endpoint | Description |
| ------ | -------- | ----------- |
| GET | `/bookings` | List all bookings |
| GET | `/bookings/{id}` | Get booking details |
| PATCH | `/bookings/{id}` | Update a booking |
| DELETE | `/bookings/{id}` | Cancel a booking |
| POST | `/bookings/{id}/confirm` | Confirm a pending booking |
| POST | `/bookings/{id}/check-in` | Check in a guest |
| POST | `/bookings/{id}/check-out` | Check out a guest |
| GET | `/guests` | List all guests |
| GET | `/guests/{id}` | Get guest details |
| GET | `/guests/search` | Search guests |
| GET | `/guests/{id}/bookings` | Get guest's booking history |

### Rate Limiting

When enabled, rate limits are applied per client (by user ID or IP address). Configure limits in **Settings → API → Rate Limits**.

**Default Limits:**

| Type | Default | Applies To |
| ---- | ------- | ---------- |
| Public | 60/min | Room/building listings |
| Availability | 30/min | Availability and calendar endpoints |
| Booking | 10/min | Booking creation |
| Admin | 120/min | All admin endpoints |

**Configuration Options:**

- **Time Window**: 10-300 seconds (default: 60 seconds)
- **Per-endpoint limits**: Customize for each endpoint type
- **Rate limiting toggle**: Enable/disable without losing settings

Rate limit headers are included in responses:

- `X-RateLimit-Limit`: Maximum requests allowed
- `X-RateLimit-Remaining`: Requests remaining in window
- `X-RateLimit-Reset`: Unix timestamp when limit resets

### Example: Check Room Availability

```bash
curl "https://site.com/wp-json/wp-bnb/v1/rooms/42/availability?check_in=2026-03-15&check_out=2026-03-20"
```

Response:

```json
{
  "available": true,
  "room_id": 42,
  "check_in": "2026-03-15",
  "check_out": "2026-03-20",
  "nights": 5,
  "pricing": {
    "base_price": 500.00,
    "seasonal_modifier": 1.0,
    "weekend_surcharge": 40.00,
    "total": 540.00,
    "currency": "CHF"
  }
}
```

### Example: Create a Booking

```bash
curl -X POST https://site.com/wp-json/wp-bnb/v1/bookings \
  -H "Content-Type: application/json" \
  -d '{
    "room_id": 42,
    "check_in": "2026-03-15",
    "check_out": "2026-03-20",
    "guests": 2,
    "guest_info": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "phone": "+41 79 123 4567"
    },
    "services": [
      {"service_id": 5, "quantity": 1}
    ],
    "notes": "Late arrival expected"
  }'
```

Response:

```json
{
  "id": 123,
  "reference": "BNB-2026-00042",
  "status": "pending",
  "room": {
    "id": 42,
    "title": "Deluxe Suite"
  },
  "check_in": "2026-03-15",
  "check_out": "2026-03-20",
  "nights": 5,
  "guests": 2,
  "pricing": {
    "room_total": 540.00,
    "services_total": 50.00,
    "grand_total": 590.00,
    "currency": "CHF"
  },
  "_links": {
    "self": [{"href": "https://site.com/wp-json/wp-bnb/v1/bookings/123"}]
  }
}
```

### Example: Search Available Rooms

```bash
curl -X POST https://site.com/wp-json/wp-bnb/v1/availability/search \
  -H "Content-Type: application/json" \
  -d '{
    "check_in": "2026-03-15",
    "check_out": "2026-03-20",
    "guests": 2,
    "amenities": ["wifi", "parking"]
  }'
```

### Error Responses

Errors follow WordPress REST API conventions:

```json
{
  "code": "rest_not_found",
  "message": "Room not found.",
  "data": {
    "status": 404
  }
}
```

Common error codes:

- `rest_invalid_param` (400): Invalid request parameters
- `rest_forbidden` (403): Insufficient permissions
- `rest_not_found` (404): Resource not found
- `rest_conflict` (409): Booking conflict
- `rest_rate_limit_exceeded` (429): Rate limit exceeded

## Frequently Asked Questions

### Do I need a license to use this plugin?

Yes, a valid license is required to use the frontend features in production. The admin functionality works without a license for evaluation purposes. Local development environments (localhost, .local, .test, .dev domains) automatically bypass license validation.

### Can I manage multiple properties?

Yes, you can create unlimited buildings and rooms.

### Is the plugin GDPR compliant?

Yes, guest data can be exported and deleted on request, and consent is tracked appropriately.

### Does it integrate with WooCommerce?

WooCommerce integration for payments is planned for a future release.

### How is guest data secured?

Sensitive guest data like passport/ID numbers are encrypted using AES-256-CBC encryption before storage. The encryption key is derived from your WordPress AUTH_KEY, ensuring data is secure at rest.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes.

## Support

For support, please create an issue at:
<https://src.bundespruefstelle.ch/magdev/wp-bnb/issues>

## Author

**Marco Graetsch**

- Website: <https://src.bundespruefstelle.ch/magdev>
- Email: <magdev3.0@gmail.com>

## License

GPL-2.0-or-later

This plugin is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or any later version.