380 lines
9.4 KiB
Markdown
380 lines
9.4 KiB
Markdown
# Software Distribution System Plan (Simplified)
|
||
|
||
Extends WooNooW Licensing with software versioning, changelog, and update checker API. Works for **any software type** - not just WordPress plugins/themes.
|
||
|
||
---
|
||
|
||
## Core Principle
|
||
|
||
**Reuse existing WooCommerce infrastructure:**
|
||
- ✅ Downloadable Product = file hosting (already exists)
|
||
- ✅ Licensing Module = license validation (already exists)
|
||
- ➕ NEW: Version tracking + changelog per product
|
||
- ➕ NEW: Update checker API endpoint
|
||
|
||
---
|
||
|
||
## What We Add (Minimal)
|
||
|
||
| Field | Type | Location |
|
||
|-------|------|----------|
|
||
| `Current Version` | Text (e.g., "1.2.3") | Product Edit |
|
||
| `Changelog` | Rich Text/Markdown | Product Edit |
|
||
| `Software Slug` | Text (unique identifier) | Product Edit |
|
||
| `Enable WP Integration` | Checkbox | Product Edit |
|
||
|
||
**If "Enable WP Integration" is checked:**
|
||
| Field | Type |
|
||
|-------|------|
|
||
| `Requires WP` | Text |
|
||
| `Tested WP` | Text |
|
||
| `Requires PHP` | Text |
|
||
| `Icon URL` | Image |
|
||
| `Banner URL` | Image |
|
||
|
||
---
|
||
|
||
## Database Schema
|
||
|
||
**Table: `wp_woonoow_software_versions`**
|
||
|
||
```sql
|
||
CREATE TABLE wp_woonoow_software_versions (
|
||
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
|
||
product_id BIGINT UNSIGNED NOT NULL,
|
||
version VARCHAR(50) NOT NULL,
|
||
changelog LONGTEXT,
|
||
release_date DATETIME NOT NULL,
|
||
is_current TINYINT(1) DEFAULT 0,
|
||
download_count INT DEFAULT 0,
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
|
||
INDEX idx_product (product_id),
|
||
INDEX idx_current (product_id, is_current),
|
||
UNIQUE KEY unique_version (product_id, version)
|
||
);
|
||
```
|
||
|
||
**Product Meta (stored in `wp_postmeta`):**
|
||
```
|
||
_woonoow_software_enabled: yes/no
|
||
_woonoow_software_slug: my-awesome-plugin
|
||
_woonoow_software_current_version: 1.2.3
|
||
_woonoow_software_wp_enabled: yes/no
|
||
_woonoow_software_requires_wp: 6.0
|
||
_woonoow_software_tested_wp: 6.7
|
||
_woonoow_software_requires_php: 7.4
|
||
_woonoow_software_icon: attachment_id or URL
|
||
_woonoow_software_banner: attachment_id or URL
|
||
```
|
||
|
||
---
|
||
|
||
## API Endpoints
|
||
|
||
### 1. Update Check (Generic)
|
||
|
||
`GET /wp-json/woonoow/v1/software/check`
|
||
|
||
**Request:**
|
||
```json
|
||
{
|
||
"license_key": "XXXX-XXXX-XXXX-XXXX",
|
||
"slug": "my-software",
|
||
"version": "1.0.0",
|
||
"site_url": "https://client-site.com"
|
||
}
|
||
```
|
||
|
||
**Response (Generic - Any Software):**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"update_available": true,
|
||
"product": {
|
||
"name": "My Awesome Software",
|
||
"slug": "my-software"
|
||
},
|
||
"current_version": "1.0.0",
|
||
"latest_version": "1.2.3",
|
||
"download_url": "https://vendor.com/wp-json/woonoow/v1/software/download?token=abc123",
|
||
"changelog_url": "https://vendor.com/wp-json/woonoow/v1/software/changelog?slug=my-software",
|
||
"changelog": "## 1.2.3\n- Fixed bug\n- Added feature",
|
||
"release_date": "2026-02-06"
|
||
}
|
||
```
|
||
|
||
**Response (WordPress Plugin/Theme - Extended):**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"update_available": true,
|
||
"product": {
|
||
"name": "My WordPress Plugin",
|
||
"slug": "my-wp-plugin"
|
||
},
|
||
"current_version": "1.0.0",
|
||
"latest_version": "1.2.3",
|
||
"download_url": "https://vendor.com/wp-json/woonoow/v1/software/download?token=abc123",
|
||
"changelog_url": "https://vendor.com/wp-json/woonoow/v1/software/changelog?slug=my-wp-plugin",
|
||
"changelog": "## 1.2.3\n- Fixed bug",
|
||
"release_date": "2026-02-06",
|
||
|
||
"wordpress": {
|
||
"requires": "6.0",
|
||
"tested": "6.7",
|
||
"requires_php": "7.4",
|
||
"icons": {
|
||
"1x": "https://vendor.com/icon-128.png",
|
||
"2x": "https://vendor.com/icon-256.png"
|
||
},
|
||
"banners": {
|
||
"low": "https://vendor.com/banner-772x250.jpg",
|
||
"high": "https://vendor.com/banner-1544x500.jpg"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**Response (No Update):**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"update_available": false,
|
||
"current_version": "1.2.3",
|
||
"latest_version": "1.2.3"
|
||
}
|
||
```
|
||
|
||
**Response (License Invalid):**
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "license_expired",
|
||
"message": "Your license has expired. Renew to receive updates."
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. Download
|
||
|
||
`GET /wp-json/woonoow/v1/software/download`
|
||
|
||
**Request:**
|
||
```
|
||
?token=abc123&license_key=XXXX-XXXX-XXXX-XXXX
|
||
```
|
||
|
||
**Response:** Binary file stream (the downloadable file from WooCommerce product)
|
||
|
||
**Token Validation:**
|
||
- One-time use token
|
||
- 5-minute expiry
|
||
- Tied to specific license
|
||
|
||
---
|
||
|
||
### 3. Changelog
|
||
|
||
`GET /wp-json/woonoow/v1/software/changelog`
|
||
|
||
**Request:**
|
||
```
|
||
?slug=my-software&version=1.2.3 (optional)
|
||
```
|
||
|
||
**Response:**
|
||
```json
|
||
{
|
||
"slug": "my-software",
|
||
"versions": [
|
||
{
|
||
"version": "1.2.3",
|
||
"release_date": "2026-02-06",
|
||
"changelog": "## 1.2.3\n- Fixed critical bug\n- Added dark mode"
|
||
},
|
||
{
|
||
"version": "1.2.0",
|
||
"release_date": "2026-01-15",
|
||
"changelog": "## 1.2.0\n- Major feature release"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Client Integration Examples
|
||
|
||
### A. WordPress Plugin (Auto-Updates)
|
||
|
||
Documented in: **woonoow-docs** → Developer → Software Updates
|
||
|
||
```php
|
||
// Include the updater class (provided by WooNooW)
|
||
require_once 'class-woonoow-updater.php';
|
||
|
||
new WooNooW_Updater([
|
||
'api_url' => 'https://your-store.com/',
|
||
'slug' => 'my-plugin',
|
||
'version' => MY_PLUGIN_VERSION,
|
||
'license_key' => get_option('my_plugin_license'),
|
||
'plugin_file' => __FILE__,
|
||
]);
|
||
```
|
||
|
||
### B. Generic Software (Manual Check)
|
||
|
||
For desktop apps, SaaS, scripts, etc:
|
||
|
||
```javascript
|
||
// Check for updates
|
||
const response = await fetch('https://vendor.com/wp-json/woonoow/v1/software/check', {
|
||
method: 'POST',
|
||
body: JSON.stringify({
|
||
license_key: 'XXXX-XXXX-XXXX-XXXX',
|
||
slug: 'my-desktop-app',
|
||
version: '1.0.0'
|
||
})
|
||
});
|
||
|
||
const data = await response.json();
|
||
if (data.update_available) {
|
||
console.log(`New version ${data.latest_version} available!`);
|
||
console.log(`Download: ${data.download_url}`);
|
||
}
|
||
```
|
||
|
||
```python
|
||
# Python example
|
||
import requests
|
||
|
||
response = requests.post('https://vendor.com/wp-json/woonoow/v1/software/check', json={
|
||
'license_key': 'XXXX-XXXX-XXXX-XXXX',
|
||
'slug': 'my-python-tool',
|
||
'version': '1.0.0'
|
||
})
|
||
|
||
data = response.json()
|
||
if data.get('update_available'):
|
||
print(f"Update available: {data['latest_version']}")
|
||
```
|
||
|
||
---
|
||
|
||
## Implementation Flow
|
||
|
||
### Product Setup (Seller)
|
||
|
||
1. Create WooCommerce product (Simple, Downloadable)
|
||
2. Enable Licensing ✓
|
||
3. Enable Software Distribution ✓
|
||
4. Set software slug: `my-software`
|
||
5. Upload downloadable file (uses existing WC functionality)
|
||
6. Set version: `1.0.0`
|
||
7. Add changelog
|
||
8. (Optional) Enable WordPress Integration → fill WP-specific fields
|
||
|
||
### Release New Version
|
||
|
||
1. Upload new file to product
|
||
2. Click "Add New Version"
|
||
3. Enter version number: `1.1.0`
|
||
4. Write changelog
|
||
5. Save → Previous version archived, new version active
|
||
|
||
### Client Updates
|
||
|
||
1. Client software calls `/software/check` with license key
|
||
2. API validates license → returns latest version info
|
||
3. Client downloads via `/software/download` with token
|
||
4. Client installs update (WordPress = automatic, others = manual/custom)
|
||
|
||
---
|
||
|
||
## Files to Create
|
||
|
||
```
|
||
includes/
|
||
├── Api/
|
||
│ └── SoftwareController.php # REST endpoints
|
||
├── Modules/
|
||
│ └── Software/
|
||
│ ├── SoftwareModule.php # Bootstrap
|
||
│ └── SoftwareManager.php # Core logic
|
||
└── Templates/
|
||
└── updater/
|
||
└── class-woonoow-updater.php # WP client library
|
||
|
||
admin-spa/src/routes/Settings/
|
||
└── Software.tsx # Version manager UI
|
||
```
|
||
|
||
---
|
||
|
||
## Documentation (woonoow-docs)
|
||
|
||
Create new section: **Developer → Software Distribution**
|
||
|
||
1. **Overview** - What is software distribution
|
||
2. **Setup Guide** - How to configure products
|
||
3. **API Reference** - Endpoint documentation
|
||
4. **WordPress Integration** - How to use the updater class
|
||
5. **Generic Integration** - Examples for non-WP software
|
||
6. **Client Libraries** - Download the updater class
|
||
|
||
---
|
||
|
||
## Implementation Phases
|
||
|
||
### Phase 1: Core ✅
|
||
- [x] Database table + product meta fields (`wp_woonoow_software_versions`, `wp_woonoow_software_downloads`)
|
||
- [x] SoftwareManager class (`includes/Modules/Software/SoftwareManager.php`)
|
||
- [x] SoftwareModule class (`includes/Modules/Software/SoftwareModule.php`)
|
||
- [x] SoftwareSettings class (`includes/Modules/SoftwareSettings.php`)
|
||
- [x] Product edit fields in WooCommerce
|
||
|
||
### Phase 2: API ✅
|
||
- [x] SoftwareController (`includes/Api/SoftwareController.php`)
|
||
- [x] `/software/check` endpoint (GET/POST)
|
||
- [x] `/software/download` endpoint with token
|
||
- [x] `/software/changelog` endpoint
|
||
|
||
### Phase 3: Admin UI ✅
|
||
- [x] Version release manager in Admin SPA (`routes/Products/SoftwareVersions/index.tsx`)
|
||
- [x] Changelog editor (Dialog with Textarea)
|
||
- [x] Version history table
|
||
|
||
### Phase 4: Client Library ✅
|
||
- [x] `class-woonoow-updater.php` for WP (`templates/updater/class-woonoow-updater.php`)
|
||
- [x] Supports both plugins and themes
|
||
- [x] Includes license status checking
|
||
|
||
### Phase 5: Documentation ✅
|
||
- [x] Add docs to woonoow-docs (`contents/docs/developer/software-updates/index.mdx`)
|
||
- [x] API reference
|
||
- [x] Integration examples (WordPress, JavaScript, Python)
|
||
|
||
---
|
||
|
||
## Security
|
||
|
||
| Measure | Description |
|
||
|---------|-------------|
|
||
| License Validation | All endpoints verify active license |
|
||
| Download Tokens | One-time use, 5-min expiry |
|
||
| Rate Limiting | Max 10 requests/minute per license |
|
||
| Signed URLs | HMAC signature for download links |
|
||
|
||
---
|
||
|
||
## Questions Before Implementation
|
||
|
||
1. ✅ Generic for any software (not just WP)
|
||
2. ✅ Reuse WooCommerce downloadable files
|
||
3. ✅ WordPress fields are optional
|
||
4. ✅ Document client library in woonoow-docs
|
||
|
||
Ready to proceed with Phase 1?
|