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
- Tests are configured for `https://streamers.channel` (live site)
- Use Browser MCP to test the site.
- Admin credentials are in the section: WordPress Admin Access

## 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
- Integrates FontAwesome CDN for frontend icons (copy buttons, etc.)

### 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
- Default download limit set to 0 (unlimited) for new products
- Proper handling of unlimited vs limited download configurations

**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
- Software license files stored locally in `wp-content/uploads/wpdd-packages/`
- Filename sanitization for downloads (spaces→dashes, dots→underscores, proper extensions)

**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
- Enhanced license key display with FontAwesome copy icons
- Improved customer purchases table layout with full-width license key rows

**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

## Recent Improvements and Bug Fixes

### Download Limits Fix (includes/class-wpdd-metaboxes.php)
- **Issue**: Products set to unlimited downloads were incorrectly showing limits instead of unlimited
- **Fix**: Changed default download limit from 5 to 0 (unlimited) in metabox configuration
- **Impact**: New products now default to unlimited downloads as intended

### License Key Display Enhancement (includes/class-wpdd-shortcodes.php, assets/css/frontend.css)
- **Improvement**: Restructured customer purchases table for better license key presentation
- **Changes**: 
  - Moved license keys from separate column to full-width spanning row
  - Added FontAwesome copy icon for easy license key copying
  - Implemented responsive CSS styling for license key display
- **New CSS Classes**: `.wpdd-license-row`, `.wpdd-license-cell`, `.wpdd-license-key`, `.wpdd-copy-icon`

### Software License Download Filename Sanitization
- **Files Modified**: `includes/class-wpdd-download-handler.php`, `includes/class-wpdd-api.php`
- **Issue**: Software license downloads had improper filenames with spaces and special characters
- **Solution**: Implemented comprehensive filename sanitization:
  - Spaces converted to dashes
  - Dots converted to underscores (except file extension)
  - Proper .zip extension enforcement
  - Version extraction from package paths
- **Example**: "Test Plugin v2.2.0" becomes "Test-Plugin-v2-2-0.zip"
- **Coverage**: Both regular download handler and API download paths

### Technical Architecture Discovery
- **Software License Storage**: Local storage in `wp-content/uploads/wpdd-packages/` (not external API)
- **Download Flow**: Token → `process_download_by_token()` → `process_download()` → `deliver_file()`
- **Dual Path Coverage**: Sanitization applied to both standard downloads and API update downloads

## 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
- FontAwesome CDN integration for UI icons

### Filename Sanitization Patterns
For software license downloads, the plugin implements standardized filename sanitization:
```php
// Pattern: Convert spaces to dashes, dots to underscores (except file extension)
$sanitized = str_replace([' ', '.'], ['-', '_'], $base_name) . '.zip';
// Example: "Test Plugin v2.2.0" → "Test-Plugin-v2-2-0.zip"
```
Applied in both `class-wpdd-download-handler.php` and `class-wpdd-api.php` for comprehensive coverage.

## Remote Deployment

**SFTP Access:**
- Host: `shadowdao@whp01.cloud-hosting.io`
- Remote path: `/streamers.channel/public_html/wp-content/plugins/wp-digital-download/`
- Use SFTP commands like: `sftp shadowdao@whp01.cloud-hosting.io`

**WordPress Admin Access:**
- Site URL: `https://streamers.channel`
- Username: `playwright`
- Password: `%Pzx*H1F(U79q6lQXsU)Ofxl`

## 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

### PayPal Sandbox Configuration
**Admin Credentials (for plugin settings):**
- Mode: Sandbox
- Client ID: `AW4tXomdLDd9tpZP6I3PsTDaDPTy5XYm1kwEu66uBUeRBFHtARweFrOAq_M9IXqYAYnBvC_YKK_n5tMI`
- Secret Key: `EOjAvXKP7wDiF_WLFRRx8Z7ccKM7ML7LpmRNSUVxzVL4wrJGq9sfDkHQAOkYEttEz0Wx_jnfPBtuFXiX`

**Test Customer Credentials (for making purchases):**
- Email: `sb-a7cpw45634739@personal.example.com`
- Password: `3[I$ppb?`

### Payment Holding System
- Default holding period: 15 days (configurable to 0 for immediate)
- Status flow: pending → available → paid
- Automated cron job processes earnings hourly
- Admin Order Manager available for cancellations/refunds
- IMPORTANT: Use Use a persistent context when using Playwright or Save and reuse authentication state when doing testing