wc-licensed-product/README.md

# WC Licensed Product

A WooCommerce plugin to sell software products using license keys with domain-based validation.

## Description

WC Licensed Product adds a new product type "Licensed Product" to WooCommerce, enabling you to sell software with automatically generated license keys. Licenses are bound to specific domains and can be validated through a REST API.

## Features

### Core Features

- **Licensed Product Type**: New WooCommerce product type for software sales
- **Automatic License Generation**: License keys generated on order completion (format: XXXX-XXXX-XXXX-XXXX)
- **Domain Binding**: Licenses are bound to customer-specified domains
- **REST API**: Public endpoints for license validation and management
- **Version Binding**: Optional binding to major software versions
- **Expiration Support**: Set license validity periods or lifetime licenses
- **Rate Limiting**: API endpoints protected with rate limiting (30 requests/minute)
- **Checkout Blocks**: Full support for WooCommerce Checkout Blocks (default since WC 8.3+)

### Customer Features

- **My Account Licenses**: Customers can view their licenses in My Account
- **License Transfers**: Customers can transfer licenses to new domains
- **Secure Downloads**: Download purchased software versions with license verification
- **Copy to Clipboard**: Easy license key copying

### Admin Features

- **License Management**: Full CRUD interface for license management
- **License Dashboard**: Statistics and analytics (WooCommerce > Reports > Licenses)
- **Search & Filtering**: Search by license key, domain, status, or product
- **Live Search**: AJAX-powered instant search results
- **Inline Editing**: Edit license status, expiry, and domain directly in the list
- **Bulk Operations**: Activate, deactivate, revoke, extend, or delete multiple licenses
- **License Transfer**: Transfer licenses to new domains
- **CSV Export/Import**: Export and import licenses via CSV
- **Order Integration**: View and manage licenses directly from order pages
- **Expiration Warnings**: Automatic email notifications before license expiration
- **Version Management**: Manage multiple versions per product with file attachments
- **Global Settings**: Default license settings via WooCommerce settings tab
- **WooCommerce HPOS**: Compatible with High-Performance Order Storage

## Requirements

- WordPress 6.0 or higher
- WooCommerce 10.0 or higher
- PHP 8.3 or higher

## Installation

1. Upload the `wc-licensed-product` folder to `/wp-content/plugins/`
2. Activate the plugin through the 'Plugins' menu in WordPress
3. The plugin will create necessary database tables on activation

## Usage

### Creating a Licensed Product

1. Go to Products > Add New
2. Select "Licensed Product" from the product type dropdown
3. Configure the product price in the General tab
4. Set license options in the "License Settings" tab:
   - **Max Activations**: Number of domains allowed per license
   - **License Validity**: Days until expiration (empty = lifetime)
   - **Bind to Major Version**: Lock license to current major version

### Managing Product Versions

1. Edit a Licensed Product
2. Use the "Product Versions" meta box to add versions
3. Upload version files via WordPress Media Library
4. Version numbers are auto-detected from filenames (e.g., `plugin-v1.2.3.zip`)

### Global Default Settings

1. Go to WooCommerce > Settings > Licensed Products
2. Set default values for Max Activations, License Validity, and Version Binding
3. Per-product settings override these defaults

### Customer Checkout

When a customer purchases a licensed product, they must enter the domain where they will use the license during checkout.

### Viewing Licenses

- **Customers**: My Account > Licenses
- **Administrators**: WooCommerce > Licenses
- **Dashboard**: WooCommerce > Reports > Licenses (for statistics)

### Exporting & Importing Licenses

**Export:**

1. Go to WooCommerce > Licenses
2. Click "Export CSV" to download all licenses

**Import:**

1. Go to WooCommerce > Licenses
2. Click "Import CSV"
3. Upload a CSV file (supports exported format or simplified format)
4. Choose options: skip header row, update existing licenses

## REST API

Full API documentation available in `openapi.json` (OpenAPI 3.1 specification).

### Response Signing (Optional)

When the server is configured with a shared secret, all API responses include cryptographic signatures for tamper protection:

**Configuration (wp-config.php):**

```php
define('WC_LICENSE_SERVER_SECRET', 'your-secure-random-string-min-32-chars');
```

**Response Headers:**

| Header | Description |
| ------ | ----------- |
| `X-License-Signature` | HMAC-SHA256 signature of the response body |
| `X-License-Timestamp` | Unix timestamp when the response was generated |

The signature prevents man-in-the-middle attacks and ensures response integrity. Use the `magdev/wc-licensed-product-client` Composer package with the `SecureLicenseClient` class to automatically verify signatures.

### Client Libraries & Examples

**PHP (Recommended):** Install the official client library via Composer:

```bash
composer require magdev/wc-licensed-product-client
```

The library provides:

- `LicenseClient` - Standard client for API calls
- `SecureLicenseClient` - Client with automatic response signature verification

**Example clients** for other languages are available in `docs/client-examples/`:

- **cURL** - Shell script examples ([curl.sh](docs/client-examples/curl.sh))
- **PHP** - Standalone client example ([php-client.php](docs/client-examples/php-client.php))
- **Python** - Client class with dataclasses ([python-client.py](docs/client-examples/python-client.py))
- **JavaScript** - Browser and Node.js client ([javascript-client.js](docs/client-examples/javascript-client.js))
- **C#** - Async client with System.Text.Json ([csharp-client.cs](docs/client-examples/csharp-client.cs))

All examples include rate limit handling (HTTP 429) and demonstrate the validate, status, and activate endpoints.

### Validate License

Validate a license key for a specific domain.

```http
POST /wp-json/wc-licensed-product/v1/validate
Content-Type: application/json

{
  "license_key": "XXXX-XXXX-XXXX-XXXX",
  "domain": "example.com"
}
```

**Success Response (200):**

```json
{
  "valid": true,
  "license": {
    "product_id": 123,
    "expires_at": "2027-01-21",
    "version_id": 5
  }
}
```

**Error Response (403):**

```json
{
  "valid": false,
  "error": "domain_mismatch",
  "message": "This license is not valid for this domain."
}
```

### Check Status

Get detailed license status information.

```http
POST /wp-json/wc-licensed-product/v1/status
Content-Type: application/json

{
  "license_key": "XXXX-XXXX-XXXX-XXXX"
}
```

**Response (200):**

```json
{
  "valid": true,
  "status": "active",
  "domain": "example.com",
  "expires_at": "2027-01-21",
  "activations_count": 1,
  "max_activations": 3
}
```

### Activate License

Activate a license on a domain.

```http
POST /wp-json/wc-licensed-product/v1/activate
Content-Type: application/json

{
  "license_key": "XXXX-XXXX-XXXX-XXXX",
  "domain": "newdomain.com"
}
```

**Response (200):**

```json
{
  "success": true,
  "message": "License activated successfully."
}
```

### Error Codes

| Code | Description |
| ---- | ----------- |
| `license_not_found` | License key does not exist |
| `license_revoked` | License has been revoked |
| `license_expired` | License has expired |
| `license_inactive` | License is inactive |
| `domain_mismatch` | License not valid for this domain |
| `max_activations_reached` | Maximum activations reached |
| `rate_limit_exceeded` | Too many requests (wait and retry) |

## License Statuses

- **Active**: License is valid and usable
- **Inactive**: License has been deactivated
- **Expired**: License validity period has ended
- **Revoked**: License has been manually revoked by admin

## Email Notifications

The plugin sends automatic email notifications:

- **Order Completion**: License keys included in order confirmation emails
- **Expiration Warning (7 days)**: Reminder sent 7 days before expiration
- **Expiration Warning (1 day)**: Urgent reminder sent 1 day before expiration

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and changes.

## Support

For issues and feature requests, please visit:
<https://src.bundespruefstelle.ch/magdev/wc-licensed-product/issues>

## Author

Marco Graetsch

## License

GPL-2.0-or-later