# CLAUDE.md

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

## Project Overview

This is a WordPress/WooCommerce plugin (Antom Payments v2.0.4, WC tested up to 9.0.0) that integrates 300+ global payment methods including digital wallets (Alipay, GCash, KakaoPay, etc.) and card payments. The plugin communicates with the Antom payment processing API and supports both classic checkout and WooCommerce Checkout Blocks.

## Development Commands

```bash
# Build assets (production)
npm run build

# Watch for changes during development
npm start

# Lint PHP files
npm run lint:php

# Auto-fix PHP linting issues
npm run lint:php-fix
```

Note: This project does not use Composer. PHP linting requires vendor directory (`./vendor/bin/phpcs`) to be set up separately.

## Architecture

### Payment Gateway Pattern

All payment gateways extend `WC_Gateway_Antom_Common` (abstract class in `includes/gateways/class-wc-gateway-antom-common.php`). Key methods:
- `process_payment($order_id)` - Initiates payment with Antom API
- `payment_notify_handler()` - Handles async webhook callbacks from Antom
- `inquiry_handler()` - Polls payment status when needed

Each gateway has:
- A gateway class in `includes/gateways/`
- A block support class in `includes/blocks/` (for Checkout Blocks integration)

### Payment Methods Registration

Payment methods are centrally defined in `includes/antom-payment-gateway-settings.php` via `antom_get_payment_methods()`. This function returns an array of configuration objects containing:
- File paths for gateway and block classes
- Gateway slug, display names, supported currencies
- Payment method type strings used in API calls

To add a new payment method, add an entry to this array with the corresponding gateway and block support files.

### SDK Layer

The `includes/sdk/` directory contains Antom API communication:
- `antom-alipay-client.php` - HTTP client with RSA signature verification
- `sdk-antom-alipay-online-request.php` - Payment request models
- `antom-signature-tool.php` - Request/response signing utilities

API hosts and paths are defined as constants in `includes/antom-payment-gateways-statement.php`.

### Model Layer

Models in `includes/model/` use `Antom_Model_Trait` for array-access pattern. Each model represents an API request section:
- `order/antom-order-model.php` is the root request model, with nested models:
  - `antom-order-buyer-model.php` - Customer information
  - `antom-order-amount-model.php` - Payment amount and currency
  - `antom-order-payment-method-model.php` - Payment method type
  - `antom-order-env-model.php` - Terminal environment info
  - `antom-order-settlement-strategy-model.php` - Settlement currency selection
  - `antom-order-name-model.php` - Product/service name
- `refund/antom-refund-model.php` - Refund request models
- `antom-model-trait.php` - Base trait for array-like access

Models use setter methods to build arrays, the `toArray()` method returns the final data structure.

### Checkout Block Integration

The plugin registers block support classes via `woocommerce_blocks_loaded` hook. Block entry points are in `resource/blocks/` and webpack outputs to `assets/blocks/`. The webpack config in `webpack.config.js` uses `@woocommerce/dependency-extraction-webpack-plugin` for WC isolation.

### Payment Flow

1. Customer selects payment method → `process_payment()` creates payment request via Antom API
2. API returns redirect URL (normalUrl) for payment initiation
3. Customer completes payment → Antom sends webhook to `payment_notify_handler()`
4. Webhook validates signature → Updates WC order status accordingly
5. Card payments may have intermediate status requiring 3DS flow (returns 'U' statusies)

Payment request IDs are stored as order meta (`_antom_request_payment_id`) to handle retries and prevent duplicate payments. Note: This stores up to `ANTOM_REQUEST_PAYMENT_KEY_LIMIT` (20) entries per order for tracking retries.

### Key Files

- `antom-payments-gateway.php` - Main plugin file with hooks for loading and initialization
- `includes/antom-payment-gateway-settings.php` - Payment method configurations
- `includes/antom-payment-gateway-statement.php` - Constants for API endpoints, URLs, and development flags
- `includes/functions.php` - Helper functions for utilities, order lookups, etc.
- `includes/class-antom-admin.php` - Admin page rendering and settings handling
- `includes/class-antom-frontend.php` - Frontend filters and order management

### Configuration

Core settings (Client ID, keys, test mode) are stored in `wp_options` under `antom_core_settings`. Settlement currencies are USD, SGD, AUD, HKD.

Development mode is controlled by `ANTOM_DEVELOP_MODE` constant in statement file - set to `true` to bypass currency restrictions during testing.