wc-licensed-product-client/CLAUDE.md

# License-Client for WooCommerce Licensed Product Plugin

**Author:** Marco Graetsch
**Author URL:** <https://src.bundespruefstelle.ch/magdev>
**Author Email:** <magdev3.0@gmail.com>
**Repository URL:** <https://src.bundespruefstelle.ch/magdev/wc-licensed-product-client>
**Issues URL:** <https://src.bundespruefstelle.ch/magdev/wc-licensed-product-client/issues>
**Package-Name:** `magdev/wc-licensed-product-client`

## Project Overview

This composer package implements a Client for the WooCommerce Licensed Product Plugin. It uses the REST API as described in `tmp/openapi.json` to activate, validate and check the status of licenses.

## Features

- Easy integration in licensed software packages
- Defines a PHP constant if a licensed is valid or not
- Obfuscate the security critical code parts using plain PHP tools as best as possible

### Key Fact: 100% AI-Generated

This project is proudly **"vibe-coded"** using Claude.AI - the entire codebase was created through AI assistance.

## Temporary Roadmap

**Note for AI Assistants:** Clean this section after the specific features are done or new releases are made. Effective changes are tracked in `CHANGELOG.md`. Do not add completed versions here - document them in the Session History section at the end of this file.

### Known Bugs

No known bugs at the moment

## Technical Stack

- **Language:** PHP 8.3.x
- **PHP-Standards:** PSR-3, PSR-4, PSR-6, PSR-18
- **Coding-Style:** Symfony
- **HTTP-Client-Library:** symfony/http-client
- **Dependency Management:** Composer
- **OpenAPI Description:** `tmp/openapi.json`

---

**For AI Assistants:**

When starting a new session on this project:

1. Read this CLAUDE.md file first
2. Semantic versioning follows the `MAJOR.MINOR.BUGFIX` pattern
3. Check git log for recent changes
4. Verify you're on the `dev` branch before making changes
5. Run `composer install` if vendor/ is missing
6. Test changes before committing
7. Follow commit message format with Claude Code attribution
8. Update this session history section with learnings
9. Always update the `README.md` on related changes
10. Keep changes in a single `CHANGELOG.md`
11. Follow markdown linting rules (see below)

Always refer to this document when starting work on this project.

### Markdown Linting Rules

When editing CLAUDE.md or other markdown files, follow these rules to avoid linting errors:

1. **MD031 - Blank lines around fenced code blocks**: Always add a blank line before and after fenced code blocks, even when they follow list items. Example of correct format:

   - **Item label**:

     (blank line here)
     \`\`\`php
     code example
     \`\`\`
     (blank line here)

2. **MD056 - Table column count**: Table separators must have matching column counts and proper spacing. Use consistent dash lengths that match column header widths.

3. **MD009 - No trailing spaces**: Remove trailing whitespace from lines

4. **MD012 - No multiple consecutive blank lines**: Use only single blank lines between sections

5. **MD040 - Fenced code blocks should have a language specified**: Always add a language identifier to code blocks (e.g., `txt`, `bash`, `php`). For shortcode examples, use `txt`.

6. **MD032 - Lists should be surrounded by blank lines**: Add a blank line before AND after list blocks, including after bold labels like `**Attributes:**`.

7. **MD034 - Bare URLs**: Wrap URLs in angle brackets (e.g., `<https://example.com>`) or use markdown link syntax `[text](url)`.

8. **Author section formatting**: Use a heading (`### Name`) instead of bold (`**Name**`) for the author name to maintain consistent document structure.

---

## Session History

### 2026-01-22 - Version 0.0.1

**Completed:**

- Initialized composer project of type `library`
- Configured package metadata (name, description, license, author)
- Set up PSR-4 autoloading for `Magdev\WcLicensedProductClient` namespace
- Added symfony/http-client ^7.0 as HTTP client dependency
- Created project structure (src/, tests/)
- Added README.md, CHANGELOG.md, and .gitignore
- Initialized git repository on `dev` branch
- Pushed initial commit to origin

**Learnings:**

- OpenAPI spec (tmp/openapi.json) defines 3 POST endpoints: `/validate`, `/status`, `/activate`
- API base path: `{baseUrl}/wp-json/wc-licensed-product/v1`
- Git remote configured via SSH: `ssh://git@src.bundespruefstelle.ch:2022/magdev/wc-licensed-product-client.git`

### 2026-01-22 - Version 0.0.2

**Completed:**

- Created `LicenseClientInterface` as public API contract
- Implemented `LicenseClient` with PSR-3 logging and PSR-6 caching support
- Added DTO classes: `LicenseInfo`, `LicenseStatus`, `ActivationResult`
- Added `LicenseState` enum for license status values (active, inactive, expired, revoked)
- Created comprehensive exception hierarchy (10 exception classes)
- Added PSR dependencies: `psr/log` ^3.0, `psr/cache` ^3.0, `psr/http-client` ^1.0
- Updated README with usage examples for basic usage, logging, caching, and exception handling
- Merged dev to main branch

**Learnings:**

- Architecture follows separation: Interface (public API) → Client (implementation) → DTOs (data) → Exceptions (errors)
- Cache keys use SHA256 hashes of license keys to avoid exposing sensitive data
- `LicenseClient` designed for obfuscation: all sensitive logic contained in single class
- Symfony HttpClient works well with PSR interfaces via `symfony/http-client-contracts`
- Keep a Changelog format allows duplicate headings per version (MD024 warning can be ignored)