wp-digital-download/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

WordPress Digital Download Plugin

This is a comprehensive WordPress plugin for creating a digital download marketplace. The plugin allows creators to sell digital products with PayPal integration, secure file protection, and watermarking capabilities.

Development Commands

Testing

• npm test - Run all Playwright E2E tests
• npm run test:headed - Run tests with browser UI visible
• npm run test:debug - Run tests in debug mode
• npm run test:ui - Run tests with Playwright UI

E2E Testing Configuration

• Tests are configured for https://streamers.channel (live site)
• Test files located in tests/e2e/
• Uses Playwright with Chromium browser
• Admin credentials stored in test file for WordPress login tests

Architecture Overview

Plugin Structure

The plugin follows WordPress standards with a singleton main class WP_Digital_Download that orchestrates all components:

Main Plugin File: wp-digital-download.php

• Defines plugin constants and initializes the main class
• Handles dependency loading and hook initialization
• Manages script/style enqueuing with cache busting

Core Components

Product Management (includes/class-wpdd-post-types.php, includes/class-wpdd-metaboxes.php)

• Custom post type wpdd_product for digital products
• Rich metadata system for pricing, files, download limits
• Creator attribution and sales tracking

Payment Processing (includes/class-wpdd-paypal.php)

• PayPal API integration (sandbox/live modes)
• Order processing and webhook handling
• Support for both paid and free products

File Security (includes/class-wpdd-file-protection.php, includes/class-wpdd-download-handler.php)

• Secure file storage outside web root
• Token-based download authentication
• Time-limited and usage-limited downloads
• Download tracking and logging

User Management (includes/class-wpdd-roles.php, includes/class-wpdd-customer.php)

• Custom roles: Digital Customer, Digital Creator
• Customer purchase history and account management
• Guest checkout support

Frontend Display (includes/class-wpdd-shortcodes.php)

• Shortcodes: [wpdd_shop], [wpdd_checkout], [wpdd_customer_purchases], etc.
• Product grids, filtering, and pagination
• Responsive design support

Admin Interface (admin/class-wpdd-admin.php, admin/class-wpdd-settings.php)

• Admin dashboard for orders and sales management
• Plugin settings and PayPal configuration
• Product editing interface

Additional Features

• Watermarking (includes/class-wpdd-watermark.php): Dynamic image/PDF watermarks
• AJAX handlers (includes/class-wpdd-ajax.php): Frontend interactions
• Installation routines (includes/class-wpdd-install.php): Database setup and pages

Database Schema

• wp_wpdd_orders - Purchase records
• wp_wpdd_downloads - Download tracking
• wp_wpdd_download_links - Secure download tokens
• Product metadata stored in wp_postmeta

Key Shortcodes

• [wpdd_shop] - Main product storefront with filtering/sorting
• [wpdd_customer_purchases] - Customer purchase history (login required)
• [wpdd_checkout] - Payment processing form
• [wpdd_thank_you] - Order confirmation page
• [wpdd_product id="123"] - Single product display

Development Notes

File Loading Pattern

All classes are loaded conditionally with existence checks and error logging. Admin classes are only loaded in admin context.

Security Considerations

• CSRF protection via nonces on all forms
• Input sanitization and validation
• Capability checks for admin functions
• Secure file delivery system
• XSS prevention in user inputs

Frontend Assets

• Cache busting using file modification times
• Separate CSS/JS for admin and frontend
• jQuery dependencies for interactive features
• Localized AJAX endpoints with nonces

Testing Strategy

Comprehensive Playwright E2E tests covering:

• Product display and search functionality
• Free download workflow (with/without account creation)
• Admin panel integration
• Security validation (CSRF, XSS prevention)
• Responsive design testing
• Performance benchmarks

Remote Deployment

• Website plugin folder is mounted locally via sshfs at /home/jknapp/remote-sftp
• Live site hosted at https://streamers.channel
• Test admin user: playwright (credentials in test files)

Important Patterns

Error Handling

Extensive error logging throughout with descriptive messages for missing classes/files.

If you find a bug or error, you should fix it in the code, deploy the changes, and test again. You should continue the process until the issue is fixed. Once you fix the issue, continue testing.

Hook System

Uses WordPress actions/filters:

• wpdd_order_completed - Post-purchase processing
• wpdd_download_started - Pre-download hooks
• wpdd_customer_registered - New customer events

Search Integration

Plugin automatically includes wpdd_product post type in WordPress search results via pre_get_posts filter.

Website Current Status

• The site is currently hooked up to PayPal Sandbox
• The website has some test products
  • One of the products is a free image and gets watermarked
  • One is a PDF for $10 and should also be watermarked

PayPal Sandbox Customer Credentials

These are sandbox only PayPal Test account. The credentials should be used to test the purchase process.

• sb-a7cpw45634739@personal.example.com
• 3[I$ppb?
• When copying files to ~/remote-sftp you MUST check if the file "THIS-IS-REMOTE" exists. If it does not exist, tell the user they need to mount the remote path.
• When using the playwright MCP, please use headless if possible.