Development

Development

Build

# Install dependencies
npm install

# Build JS bundles
npm run build

# Watch for changes
npm run watch

Three JavaScript bundles are built with esbuild (build.mjs):

• assets/js/clink-checkout.js — uses @shocknet/clink-sdk to request Lightning invoices via the CLINK protocol on the order-received page. QR codes are generated client-side with qrcode-generator (no remote API). Built to clink-checkout.min.js.
• assets/js/clink-blocks.js — registers the gateway with WooCommerce Cart/Checkout Blocks via registerPaymentMethod(). Built to clink-blocks.min.js.
• assets/js/clink-price-converter.js — client-side price conversion fallback that converts .woocommerce-Price-amount elements to sats/BTC/₿ on all frontend pages. Ensures compatibility with price-display plugins like Custom Price for WooCommerce Pro. Built to clink-price-converter.min.js.

The release .zip ships the pre-built .min.js bundles, so consumers never need Node.js.

Architecture

Checkout Flow:
  Customer                    WooCommerce                  Nostr Relay          Merchant Node
     │                           │                           │                     │
     │── Place Order ───────────▶│                           │                     │
     │                           │── Create Order (pending)  │                     │
     │                           │── Redirect to thank-you   │                     │
     │                           │                           │                     │
     │── Page Load ─────────────▶│                           │                     │
     │                           │── Localize noffer + sats  │                     │
     │                           │                           │                     │
     │── JS: Decode noffer ──────┤                           │                     │
     │── JS: Generate ephemeral  │                           │                     │
     │     Nostr key             │                           │                     │
     │── JS: Send kind:21001 ────┼──────────────────────────▶│── Request Invoice ─▶│
     │                           │                           │                     │
     │                           │◀── BOLT 11 Invoice ──────│◀─ Response ─────────│
     │── Display QR code ◀──────┤                           │                     │
     │── Customer pays ◀─────────┼──────────────────────────▶│                     │
     │                           │                           │── Receipt ─────────▶│
     │◀── Receipt callback ──────┤◀──────────────────────────│                     │
     │── AJAX: mark_paid ───────▶│                           │                     │
     │                           │── Order complete ────────▶│                     │

Files

woocommerce-clink-gateway/
├── woocommerce-clink-gateway.php        # Plugin bootstrap, AJAX handlers, scripts
├── includes/
│   ├── class-wc-gateway-clink.php       # WC_Payment_Gateway implementation
│   ├── class-wc-clink-subscriptions.php # WooCommerce Subscriptions integration
│   └── class-wc-clink-blocks-support.php# Cart/Checkout Blocks support
├── assets/
│   ├── js/
│   │   ├── clink-checkout.js            # Source — order-received page (ES module, @shocknet/clink-sdk)
│   │   ├── clink-checkout.min.js        # Built bundle
│   │   ├── clink-blocks.js             # Source — blocks checkout registration
│   │   ├── clink-blocks.min.js         # Built bundle
│   │   ├── clink-price-converter.js    # Source — client-side price conversion fallback
│   │   ├── clink-price-converter.min.js# Built bundle
│   │   └── clink-checkout.asset.php    # Asset metadata
│   ├── css/clink-checkout.css           # Checkout page styles
│   └── images/lightning-icon.svg        # Payment method icon
├── build.mjs                            # esbuild config
└── package.json                         # NPM dependencies

Releasing

1. Bump the version in woocommerce-clink-gateway.php, package.json, and readme.txt (stable tag + changelog)
2. Rebuild the JS bundles with npm run build
3. Rebuild the release .zip (excluding node_modules, .git, and build files)
4. Tag and create a GitHub release, then deploy trunk + tag to WordPress.org SVN