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