Soundwave (Affiliate → Hub Woo Sync) — Blueprint README

Blueprint you can build from: This README is a complete, GitHub‑ready spec that lets you create the Soundwave WooCommerce plugin from scratch, package it, and deploy it. It includes folder layout, minimal production code scaffolds, build/package steps, auto‑sync hooks, the manual Sync UI, and Hub admin snippets (thumbnail + lightbox).

TL;DR

• Purpose: Push WooCommerce orders from an Affiliate site to a Hub WooCommerce site through the Hub’s REST API (v3).
• Manual: “Sync” button on the admin orders table (with “Fix errors” link if validation fails).
• Automatic: Sync on thankyou, payment_complete, and order_status_processing.
• Validation: Each line item must resolve product custom fields:
  Company Name, Print Location, Production, Original Art, Site Slug, Vendor Code.
• Mapping: Sends billing/shipping, line items (with variation SKU, Parent SKU, attributes (no dupes)), shipping/fees, and order meta. Forces Hub status to processing and sets set_paid when appropriate.
• Resync awareness: If the item is deleted/trashed on the Hub, the Affiliate detects unsynced state and the Sync button returns.

Features

• Admin orders list column showing Sync state:
  • ✅ Synced text for orders known to exist on the Hub.
  • 🔁 Sync button with spinner and Fix errors link when validation fails.
• Auto‑Sync hooks (single guarded attempt):
  • woocommerce_thankyou
  • woocommerce_payment_complete
  • woocommerce_order_status_processing
• Manual AJAX sync: wp_ajax_soundwave_sync_order
• Hub status checker: wp_ajax_soundwave_check_status (batch)
• Robust line‑item meta:
  • Adds Variation SKU (and Parent SKU), deduplicates Color/Size.
  • Appends six product custom fields (variation → parent fallback).
  • Sends Product Image URL per line for Hub UI.
• Error notes written to the order + _soundwave_last_error meta.
• Debug meta: _soundwave_last_payload, _soundwave_last_response_code, _soundwave_last_response_body.

Requirements

• WordPress 6.x
• WooCommerce 7.x+ (HPOS compatible admin tested)
• PHP 7.4+ (8.0+ recommended)
• Hub (target) must expose WooCommerce REST API v3 endpoints and keys with write access to orders.

Folder Structure (GitHub repo)

IMPORTANT: The plugin must install into a folder named exactly soundwave/. The ZIP you upload should contain a root folder named soundwave (not soundwave-vX.Y.Z).

soundwave/                    ← plugin root folder (this exact name matters)
├── soundwave.php             ← main plugin file (headers, constants, boot)
├── includes/
│   ├── utils.php             ← payload builder, helpers, hub status, etc.
│   └── validator.php         ← field lookups & per-order validation
├── sync.php                  ← admin column, AJAX handlers, auto-sync hooks
├── assets/
│   ├── admin.css             ← minimal styling for button/spinner
│   └── admin.js              ← Sync button JS + row updates
├── readme.md                 ← this file (kept in repo for devs)
└── README.md                 ← GitHub facing (this file; you can keep one)

You can keep both readme.md (lowercase, WP.org style if you ever publish there) and README.md (GitHub style). This blueprint uses README.md.

Installation (Developer)

1. Clone into wp-content/plugins/ as soundwave:

   cd wp-content/plugins
   git clone https://github.com/your-org/soundwave.git soundwave

2. Activate Soundwave in WP Admin → Plugins.
3. Set options (see Configuration).

Packaging a Release ZIP

Ensure the ZIP root folder is soundwave/.

# from the parent directory containing the `soundwave/` folder
zip -r soundwave-v1.4.21.zip soundwave -x "soundwave/.git/*" "soundwave/.github/*" "soundwave/node_modules/*"

Upload soundwave-v1.4.21.zip in WP Admin → Plugins → Add New → Upload Plugin.

Configuration

The plugin reads settings from the single option soundwave_settings:

[
  'endpoint'        => 'https://hubsite.com/wp-json/wc/v3/orders',
  'consumer_key'    => 'ck_xxxxx',
  'consumer_secret' => 'cs_xxxxx',
]

You can set these via WP‑CLI:

wp option update soundwave_settings \
'{"endpoint":"https://thebeartraxs.com/wp-json/wc/v3/orders","consumer_key":"ck_XXX","consumer_secret":"cs_XXX"}' \
--format=json

Or drop a one‑time snippet in a must‑use plugin to initialize them.

Minimal Production Code (copy/paste scaffolds)

These are minimal, working baselines distilled from our working implementation. Paste these files to get a fully functional plugin and adjust as desired.

soundwave.php

<?php
/**
 * Plugin Name: Soundwave
 * Description: Affiliate → Hub WooCommerce order sync (manual + auto).
 * Version: 1.4.21
 * Author: Your Company
 */

if (!defined('ABSPATH')) exit;

define('SOUNDWAVE_VERSION', '1.4.21');
define('SOUNDWAVE_DIR', plugin_dir_path(__FILE__));
define('SOUNDWAVE_URL', plugin_dir_url(__FILE__));

// Hard fail notice if the folder name is wrong (optional safety)
add_action('admin_init', function () {
    $expected = WP_PLUGIN_DIR . '/soundwave/soundwave.php';
    if (!file_exists($expected)) {
        add_action('admin_notices', function () {
            echo '<div class="notice notice-error"><p><strong>Soundwave:</strong> Plugin folder must be <code>soundwave/</code>. Repackage your ZIP with that root folder name.</p></div>';
        });
    }
});

require_once SOUNDWAVE_DIR . 'includes/utils.php';
require_once SOUNDWAVE_DIR . 'includes/validator.php';
require_once SOUNDWAVE_DIR . 'sync.php';