WooNooW/.agent/plans/software-distribution.md

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

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:

{
  "license_key": "XXXX-XXXX-XXXX-XXXX",
  "slug": "my-software",
  "version": "1.0.0",
  "site_url": "https://client-site.com"
}

Response (Generic - Any Software):

{
  "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):

{
  "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):

{
  "success": true,
  "update_available": false,
  "current_version": "1.2.3",
  "latest_version": "1.2.3"
}

Response (License Invalid):

{
  "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:

{
  "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

// 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:

// 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 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 ✅

• Database table + product meta fields (wp_woonoow_software_versions, wp_woonoow_software_downloads)
• SoftwareManager class (includes/Modules/Software/SoftwareManager.php)
• SoftwareModule class (includes/Modules/Software/SoftwareModule.php)
• SoftwareSettings class (includes/Modules/SoftwareSettings.php)
• Product edit fields in WooCommerce

Phase 2: API ✅

• SoftwareController (includes/Api/SoftwareController.php)
• /software/check endpoint (GET/POST)
• /software/download endpoint with token
• /software/changelog endpoint

Phase 3: Admin UI ✅

• Version release manager in Admin SPA (routes/Products/SoftwareVersions/index.tsx)
• Changelog editor (Dialog with Textarea)
• Version history table

Phase 4: Client Library ✅

• class-woonoow-updater.php for WP (templates/updater/class-woonoow-updater.php)
• Supports both plugins and themes
• Includes license status checking

Phase 5: Documentation ✅

• Add docs to woonoow-docs (contents/docs/developer/software-updates/index.mdx)
• API reference
• 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?