# Changelog

All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [v1.3.0] - 2026-05-03
### Added
- `src/models/Product.php` — value object for VirtualStock catalogue products; `fromArray()`, `toArray()`, `isIdentifiable()`, supports both snake_case and alternative key names
- `src/models/StockLevel.php` — value object for product stock levels; `fromArray()`, `toArray()`, `isAvailable()` (checks quantity > 0 or affirmative status string)
- `src/services/ProductService.php` — `listProducts()`, `getProduct()`, `getStockLevel()`, `searchProducts()` using `VirtualStockClient`
- `VirtualStockClient::listProducts()` — query product catalogue with optional filters
- `tests/unit/exceptions/ExceptionTest.php` — unit tests for all four exception classes
- `tests/unit/helpers/DateTimeHelperTest.php` — unit tests for `DateTimeHelper`
- `docs/ORDER_MANAGEMENT.md` — order lifecycle guide, status workflow, code examples, Screwfix notes, error handling, date formatting

### Fixed
- Testing framework items completed: unit tests for all models, constants, helpers, and exceptions

## [v1.2.1] - 2026-05-03
### Added
- `src/models/ConfigForm` — settings model with `loadFromParams()`, `saveToParams()` (encrypts API key/secret), `testConnection()`, validation rules, and attribute hints
- `src/controllers/ConfigController` — web controller with `actionIndex()` (save), `actionTestConnection()` (AJAX POST), `actionStatus()` (AJAX GET cursor/state), `actionImport()` (AJAX POST on-demand import with dry-run support)
- `src/views/config/index.php` — Bootstrap 4 configuration UI with API settings, import settings, advanced settings, live status panel, and on-demand import trigger

### Changed
- `Module` — added `$enabled` and `$debug` properties; `isConfigured()` now also checks `$enabled`; both new properties wired into `loadConfigFromParams()`

## [v1.2.0] - 2026-05-03
### Added
- `src/exceptions/` — `ApiException`, `AuthenticationException` (403), `ValidationException` (500), `RateLimitException` (429) with structured error context
- `src/constants/OrderStatus` — all primary and RMA statuses, labels map, transitions map, `canTransitionTo()` / `nextStatuses()`
- `src/constants/ShipmentStatus` — all tracking statuses, labels, active/terminal sets
- `src/constants/ApiEndpoints` — sandbox/production base URLs, resource path constants, `resolve()` template helper
- `src/models/Order` — value object with `fromArray()`/`toArray()`, item collection, shipping address, status helpers
- `src/models/OrderItem` — line item value object with `toAcknowledgePayload()` for the acknowledge endpoint (Screwfix 'Booked' support included)
- `src/models/ShippingAddress` — delivery address value object with UK postcode validation and completeness check
- `src/services/OrderService` — `listOrders()`, `getOrder()`, `acknowledgeOrder()`, `dispatchOrder()`, `cancelOrder()`, `iterateOrders()` (Generator-based pagination)
- `src/helpers/StatusHelper` — convenience façade over OrderStatus/ShipmentStatus constants
- `src/helpers/DateTimeHelper` — ISO 8601 UTC formatting/parsing, `daysFromNow()`, `isPast()`

### Changed
- `VirtualStockClient::request()` now throws typed exceptions (`AuthenticationException`, `RateLimitException`, `ApiException`) instead of `\RuntimeException`

## [v1.1.1] - 2026-05-03
### Changed
- Replaced `guzzlehttp/guzzle` with `yiisoft/yii2-httpclient` in `VirtualStockClient` for consistency with the NGauge module standard

## [v1.1.0] - 2026-05-03
### Added
- `OrderImportController` — console command `virtualstock/order-import/run` with `--cursor`, `--limit`, `--dry-run` options
- `OrderImportService` — pull-based, cursor-driven order import with idempotent cart/cartline upsert
- `VirtualStockCursorStore` — persistent cursor state via Yii cache with flat-file fallback
- `VirtualStockClient` — Guzzle-backed HTTP client with Basic Auth, `getOrdersUpdatedSince`, `getOrder`, `getProduct`, `getProductStock`
- `models/carts/Virtualstock` — DynamicModel for order cart attributes (order_no, status, last_sync, updated_at_source, shipments_json)
- `models/products/Virtualstock` — DynamicModel for product attributes (supplier_sku, lead_time, supplier_code, last_sync)
- Module bootstrap registers console command namespace and data-type hooks automatically

### Changed
- `Module.php` expanded with full configuration surface: `apiKey`, `apiSecret`, `requestTimeout`, `pollLimit`, `orderNumberPrefix`, `orderImportCursorKey`, `orderImportCursorFile`, `statusMap`
- PLAN.md and TODO.md docs added to repository

## [v1.0.0] - 2026-03-06
### Added
- Initial release — Yii2 module scaffold
- `composer.json` with PSR-4 autoload under `PortalPeople\virtualstock\`
- Basic `Module.php` stub
- README, LICENSE, CHANGELOG stubs
