feat/fix: checkout email tracing, UI tweaks for add-to-cart, cart page overflow fix, implement hide admin bar setting
This commit is contained in:
Dwindi Ramadhana
379
.agent/plans/software-distribution.md
Normal file
379
.agent/plans/software-distribution.md
Normal file
@@ -0,0 +1,379 @@
|
||||
# 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?
|
||||
Reference in New Issue
Block a user