# CLAUDE.md

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

## Project Overview

WooCommerce shipping plugin for Iceland Post (Pósturinn). Integrates with the Mappan API for real-time rate calculation, shipment creation, PDF label generation, and tracking. Supports domestic services (home delivery, post office, postbox, parcel lockers) and international shipping.

**Plugin slug:** `postis` | **Version:** 1.4.7 | **Text domain:** `postis` | **Min PHP:** 7.4

## Development Setup

This is a WordPress plugin with no build step. Install directly into `wp-content/plugins/` of a WordPress + WooCommerce installation. Vendored dependencies live in `lib/` (FPDI for PDFs, LAFFPack for carton packing) — no `composer install` or `npm install` needed at the root.

There are no tests, linting, or CI/CD configured.

## Architecture

### Dual Code Paths (HPOS)

The plugin maintains two parallel code directories to support WooCommerce's High-Performance Order Storage:

- **`inc/`** — Legacy postmeta-based order storage
- **`inc_hpos/`** — HPOS custom order tables

`postis_hpos_active()` in the main file detects which mode WooCommerce is using and loads the corresponding directory. Both paths have identical files with near-identical logic. **Changes must be applied to both directories.**

Similarly, `templates/` and `templates_hpos/` hold the respective order/shipment templates.

### Bootstrap Flow

`wc-posturinn-shipping-api.php` → defines constants (`POSTIS_PATH`, `POSTIS_URL`, `POSTIS_PDF_DIR`) → hooks `postis_include_files()` on `plugins_loaded` → loads all class files from the active code path → instantiates `POSTIS_MAIN_CLASS` singleton → registers shipping method, scripts, hooks.

### Core Classes (in `inc/` and `inc_hpos/`)

| File | Class | Role |
|------|-------|------|
| `postis.class.php` | `POSTIS_Shipping` | WC_Shipping_Method implementation. Calculates rates via LAFFPack packing + Mappan API. Manages all shipping settings. |
| `api.class.php` | `POSTIS_API` | HTTP client for Mappan API — shipment creation, PDF retrieval, rate calculation, postbox/parcel point lookup, kennitala validation. |
| `admin.class.php` | `POSTIS_Admin` | Admin UI — order list columns, shipment metabox, AJAX handlers for create/delete/PDF, bulk actions, product meta fields. |
| `checkout-fields.class.php` | `POSTIS_Checkout_Fields` | Custom checkout fields — kennitala (Icelandic national ID), postbox selection, parcel point selection, phone numbers. |
| `functions.php` | — | Helpers: `postis_get_settings()`, `postis_get_endpoints()`, `postis_get_plugin_mode()`, endpoint URL maps. |
| `hooks.php` | — | WooCommerce action/filter hooks for order processing, email integration. |
| `blocks-support.php` | `Postis_Blocks_Integration` | WooCommerce Blocks checkout integration — AJAX postbox/parcel data, Store API hooks, script registration. |

### Shipping Service Codes

| Code | Service | Scope |
|------|---------|-------|
| DPH | Pakki Heim (home delivery) | Domestic |
| DPP | Pakki Pósthús (post office) | Domestic |
| DPO | Pakki Póstbox (postbox) | Domestic |
| DNO | Pakki Póstbox (legacy) | Domestic |
| DPL | Pakki Landspóstur (regional) | Domestic |
| DPT | Pakki Pakkaport (parcel locker) | Domestic |
| OLP | Smápakki til útlanda | International |
| OIJ | Pakki til Útlanda | International |

### API Integration

- **Live base:** `https://api.mobiz.posturinn.is/api/`
- **Demo/test base:** `https://apitest.mappan.is/`
- Mode controlled by `postis_get_plugin_mode()` — returns `'live'` or `'demo'`
- Auth via `x-api-key` header (configured in WC shipping settings)
- Key endpoints: `/wscm/v1/deliveryservicesandprices`, `/wscm/v1/shipments/create`, `/wscm/v1/postboxes`, `/wscm/v1/parcelpoints`

### Settings Storage

All plugin settings stored in a single WP option: `woocommerce_postis_settings`. Access via `postis_get_settings($key)`. Order-level data stored as order meta (`postis_shipping_method`, `postis_shipment_data`, `postis_dpo_postbox`, `postis_dpt_parcelpoints`, etc.).

### Checkout Support

The plugin supports both legacy shortcode checkout and WooCommerce Blocks checkout. Postbox (DPO) and parcel point (DPT) selections require additional UI — a dropdown + phone number field rendered after shipping method selection, with optional Google Maps modal for postbox selection.