Add Grafana dashboard and wp-prometheus integration (v0.7.5)

- Add example Grafana dashboard with 24 panels for license metrics - Register dashboard with wp-prometheus via hook - Add dashboard documentation with PromQL examples and alerting rules - Update README with monitoring section Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add MARKETING.md to .gitignore
2026-02-03 11:29:14 +01:00 · 2026-02-03 10:58:30 +01:00 · 2026-02-03 10:57:01 +01:00 · 2026-02-03 10:52:50 +01:00 · 2026-02-01 13:53:37 +01:00 · 2026-02-01 13:52:57 +01:00
23 changed files with 6387 additions and 3371 deletions
--- a/.gitea/workflows/release.yml
+++ b/.gitea/workflows/release.yml
@@ -0,0 +1,228 @@
+name: Create Release Package
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          extensions: mbstring, xml, zip, intl, gettext
+          tools: composer:v2
+
+      - name: Get version from tag
+        id: version
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Building version: $VERSION"
+
+      - name: Validate composer.json
+        run: composer validate --no-check-lock --no-check-all
+
+      - name: Install Composer dependencies (production)
+        run: |
+          composer config platform.php 8.3.0
+          composer install --no-dev --optimize-autoloader --no-interaction
+
+      - name: Fix vendor symlink
+        run: |
+          # If client is a symlink, replace with actual files
+          if [ -L "vendor/magdev/wc-licensed-product-client" ]; then
+            echo "Found symlink, replacing with actual files..."
+            TARGET=$(readlink -f vendor/magdev/wc-licensed-product-client)
+            rm vendor/magdev/wc-licensed-product-client
+            cp -r "$TARGET" vendor/magdev/wc-licensed-product-client
+          fi
+          ls -la vendor/magdev/
+
+      - name: Install gettext
+        run: apt-get update && apt-get install -y gettext
+
+      - name: Compile translations
+        run: |
+          for po in languages/*.po; do
+            if [ -f "$po" ]; then
+              mo="${po%.po}.mo"
+              echo "Compiling $po to $mo"
+              msgfmt -o "$mo" "$po"
+            fi
+          done
+
+      - name: Verify plugin version matches tag
+        run: |
+          PLUGIN_VERSION=$(grep -oP "Version:\s*\K[0-9]+\.[0-9]+\.[0-9]+" wc-licensed-product.php | head -1)
+          TAG_VERSION=${{ steps.version.outputs.version }}
+          if [ "$PLUGIN_VERSION" != "$TAG_VERSION" ]; then
+            echo "Error: Plugin version ($PLUGIN_VERSION) does not match tag version ($TAG_VERSION)"
+            exit 1
+          fi
+          echo "Version verified: $PLUGIN_VERSION"
+
+      - name: Create release directory
+        run: mkdir -p releases
+
+      - name: Build release package
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          PLUGIN_NAME="wc-licensed-product"
+          RELEASE_FILE="releases/${PLUGIN_NAME}-${VERSION}.zip"
+
+          cd ..
+          zip -r "${PLUGIN_NAME}/${RELEASE_FILE}" "${PLUGIN_NAME}" \
+            -x "${PLUGIN_NAME}/.git/*" \
+            -x "${PLUGIN_NAME}/.gitea/*" \
+            -x "${PLUGIN_NAME}/.github/*" \
+            -x "${PLUGIN_NAME}/.vscode/*" \
+            -x "${PLUGIN_NAME}/.claude/*" \
+            -x "${PLUGIN_NAME}/CLAUDE.md" \
+            -x "${PLUGIN_NAME}/wp-core" \
+            -x "${PLUGIN_NAME}/wp-core/*" \
+            -x "${PLUGIN_NAME}/wp-plugins" \
+            -x "${PLUGIN_NAME}/wp-plugins/*" \
+            -x "${PLUGIN_NAME}/releases/*" \
+            -x "${PLUGIN_NAME}/composer.lock" \
+            -x "${PLUGIN_NAME}/*.log" \
+            -x "${PLUGIN_NAME}/.gitignore" \
+            -x "${PLUGIN_NAME}/.gitmodules" \
+            -x "${PLUGIN_NAME}/.editorconfig" \
+            -x "${PLUGIN_NAME}/phpcs.xml*" \
+            -x "${PLUGIN_NAME}/phpunit.xml*" \
+            -x "${PLUGIN_NAME}/tests/*" \
+            -x "${PLUGIN_NAME}/*.po~" \
+            -x "${PLUGIN_NAME}/*.bak" \
+            -x "${PLUGIN_NAME}/lib/*" \
+            -x "${PLUGIN_NAME}/lib/*/.git/*" \
+            -x "${PLUGIN_NAME}/vendor/magdev/*/.git/*" \
+            -x "${PLUGIN_NAME}/vendor/magdev/*/CLAUDE.md" \
+            -x "*.DS_Store"
+
+          cd "${PLUGIN_NAME}"
+          echo "Created: ${RELEASE_FILE}"
+          ls -lh "${RELEASE_FILE}"
+
+      - name: Generate checksums
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          PLUGIN_NAME="wc-licensed-product"
+
+          cd releases
+          sha256sum "${PLUGIN_NAME}-${VERSION}.zip" > "${PLUGIN_NAME}-${VERSION}.zip.sha256"
+          echo "SHA256:"
+          cat "${PLUGIN_NAME}-${VERSION}.zip.sha256"
+
+      - name: Verify package structure
+        run: |
+          set +o pipefail
+          VERSION=${{ steps.version.outputs.version }}
+          PLUGIN_NAME="wc-licensed-product"
+
+          echo "Package contents (first 50 entries):"
+          unzip -l "releases/${PLUGIN_NAME}-${VERSION}.zip" | head -50 || true
+
+          # Verify main plugin file exists
+          if unzip -l "releases/${PLUGIN_NAME}-${VERSION}.zip" | grep -q "${PLUGIN_NAME}/${PLUGIN_NAME}.php"; then
+            echo "Main plugin file: OK"
+          else
+            echo "ERROR: Main plugin file not found!"
+            exit 1
+          fi
+
+          # Verify vendor directory included
+          if unzip -l "releases/${PLUGIN_NAME}-${VERSION}.zip" | grep -q "${PLUGIN_NAME}/vendor/"; then
+            echo "Vendor directory: OK"
+          else
+            echo "ERROR: Vendor directory not found!"
+            exit 1
+          fi
+
+          # Verify lib directory excluded
+          if unzip -l "releases/${PLUGIN_NAME}-${VERSION}.zip" | grep -q "${PLUGIN_NAME}/lib/"; then
+            echo "WARNING: lib/ directory should be excluded"
+          else
+            echo "lib/ excluded: OK"
+          fi
+
+      - name: Extract changelog for release notes
+        id: changelog
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          NOTES=$(sed -n "/^## \[${VERSION}\]/,/^## \[/p" CHANGELOG.md | sed '$ d' | tail -n +2)
+          if [ -z "$NOTES" ]; then
+            NOTES="Release version ${VERSION}"
+          fi
+          echo "$NOTES" > release_notes.txt
+          echo "Release notes extracted"
+
+      - name: Create Gitea Release
+        env:
+          GITEA_TOKEN: ${{ secrets.SRC_GITEA_TOKEN }}
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          TAG_NAME=${{ github.ref_name }}
+          PLUGIN_NAME="wc-licensed-product"
+
+          PRERELEASE="false"
+          if [[ "$TAG_NAME" == *-* ]]; then
+            PRERELEASE="true"
+          fi
+
+          BODY=$(cat release_notes.txt)
+
+          # Check if release already exists and delete it
+          EXISTING_RELEASE=$(curl -s \
+            -H "Authorization: token ${GITEA_TOKEN}" \
+            "${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}/releases/tags/${TAG_NAME}")
+
+          EXISTING_ID=$(echo "$EXISTING_RELEASE" | jq -r '.id // empty')
+          if [ -n "$EXISTING_ID" ] && [ "$EXISTING_ID" != "null" ]; then
+            echo "Deleting existing release ID: $EXISTING_ID"
+            curl -s -X DELETE \
+              -H "Authorization: token ${GITEA_TOKEN}" \
+              "${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}/releases/${EXISTING_ID}"
+            echo "Existing release deleted"
+          fi
+
+          # Create release via Gitea API
+          RELEASE_RESPONSE=$(curl -s -X POST \
+            -H "Authorization: token ${GITEA_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "{\"tag_name\": \"${TAG_NAME}\", \"name\": \"Release ${VERSION}\", \"body\": $(echo "$BODY" | jq -Rs .), \"draft\": false, \"prerelease\": ${PRERELEASE}}" \
+            "${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}/releases")
+
+          RELEASE_ID=$(echo "$RELEASE_RESPONSE" | jq -r '.id')
+
+          if [ "$RELEASE_ID" == "null" ] || [ -z "$RELEASE_ID" ]; then
+            echo "Failed to create release:"
+            echo "$RELEASE_RESPONSE"
+            exit 1
+          fi
+
+          echo "Created release ID: $RELEASE_ID"
+
+          # Upload release assets
+          for file in "releases/${PLUGIN_NAME}-${VERSION}.zip" "releases/${PLUGIN_NAME}-${VERSION}.zip.sha256"; do
+            if [ -f "$file" ]; then
+              FILENAME=$(basename "$file")
+              echo "Uploading $FILENAME..."
+              curl -s -X POST \
+                -H "Authorization: token ${GITEA_TOKEN}" \
+                -H "Content-Type: application/octet-stream" \
+                --data-binary "@$file" \
+                "${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}/releases/${RELEASE_ID}/assets?name=${FILENAME}"
+              echo "Uploaded $FILENAME"
+            fi
+          done
+
+          echo "Release created: ${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/releases/tag/${TAG_NAME}"
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,6 @@ wp-plugins
 wp-core
 vendor/
 releases/*
+
+# Marketing texts (not part of plugin distribution)
+MARKETING.md
--- a/.gitmodules
+++ b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "lib/wc-licensed-product-client"]
+	path = lib/wc-licensed-product-client
+	url = ../wc-licensed-product-client.git
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,95 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+## [0.7.5] - 2026-02-03
+
+### Added
+
+- **Grafana Dashboard**: Example dashboard for license metrics monitoring
+  - 24 panels organized into 4 sections: License Overview, Downloads & Versions, API Metrics, Errors & Rate Limiting
+  - Template variables for data source and instance filtering
+  - Includes example Prometheus alerting rules
+- **WP Prometheus Dashboard Integration**: Dashboard automatically registered with wp-prometheus
+  - Appears in Settings > WP Prometheus > Dashboards when metrics are enabled
+  - Uses `wp_prometheus_register_dashboards` hook for seamless integration
+- Documentation for Grafana dashboard installation and PromQL query examples
+
+### New Files
+
+- `docs/grafana-dashboard.json` - Complete Grafana dashboard with 24 panels
+- `docs/grafana-dashboard.md` - Installation and usage documentation
+
+### Changed
+
+- Updated README with "Monitoring with Prometheus & Grafana" section
+
+## [0.7.4] - 2026-02-03
+
+### Added
+
+- **Prometheus Metrics Integration**: Expose license and API metrics for monitoring
+  - New "Metrics" settings tab with enable/disable toggle
+  - License gauges: total by status, lifetime, expiring, expiring soon
+  - Download gauges: total downloads, active versions count
+  - API counters: requests by endpoint/result, rate limit exceeded events, validation errors by type
+  - Requires [WP Prometheus](https://src.bundespruefstelle.ch/magdev/wp-prometheus) plugin
+
+### New Files
+
+- `src/Metrics/PrometheusController.php` - Prometheus metrics collection and registration
+
+### Technical Details
+
+- Hooks into `wp_prometheus_collect_metrics` action for metric collection
+- API counters stored persistently in WordPress options (`wclp_prometheus_counters`)
+- Static methods for incrementing counters from API controllers
+- Metrics only collected when enabled in settings
+
+## [0.7.3] - 2026-02-01
+
+### Fixed
+
+- **Docker Environment Support:** API Verification Secret now visible on customer licenses page in Docker environments
+  - Added `ResponseSigner::getServerSecret()` method to check multiple sources for server secret
+  - Checks PHP constant, `getenv()`, `$_ENV`, and `$_SERVER` in priority order
+  - Maintains full backward compatibility with standard WordPress installations
+
+### Changed
+
+- Updated `Plugin.php` to use `ResponseSigner::isSigningEnabled()` instead of direct constant check
+
+### Technical Details
+
+- Root cause: Docker WordPress setups using `wp-config-docker.php` with `getenv_docker()` don't always define PHP constants
+- The environment variable was accessible but the constant wasn't being created
+- New `getServerSecret()` method centralizes all server secret retrieval logic
+
+## [0.7.2] - 2026-01-29
+
+### Added
+
+- **Gitea CI/CD Pipeline**: Automated release workflow triggered on version tags
+  - Automatic package creation with proper WordPress subdirectory structure
+  - SHA256 checksum generation for package integrity
+  - Changelog extraction for release notes
+  - Pre-release detection for hyphenated tags (e.g., `v0.7.2-rc1`)
+
+### Changed
+
+- **Git Submodule Migration**: `magdev/wc-licensed-product-client` is now a git submodule
+  - Located at `lib/wc-licensed-product-client` instead of being fetched via Composer VCS
+  - Composer now uses `path` type repository pointing to local submodule
+  - Improves version control clarity and development workflow
+  - Symlinked to `vendor/` during `composer install`
+
+### Developer Notes
+
+- New file: `.gitea/workflows/release.yml` for CI/CD automation
+- Updated `composer.json`: Repository type changed from `vcs` to `path`
+- Created `.gitmodules` for submodule tracking
+- Release packages now exclude `lib/` directory (vendor has installed copy)
+- Submodule checkout required: `git submodule update --init --recursive`
+
 ## [0.7.1] - 2026-01-28

 ### Fixed
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -32,9 +32,9 @@ This project is proudly **"vibe-coded"** using Claude.AI - the entire codebase w

 **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.

-### Version 0.7.2
+### Known Bugs

-No pending features.
+None currently tracked.

 ## Technical Stack

@@ -1872,3 +1872,198 @@ Bug fix release ensuring compatibility with updated `magdev/wc-licensed-product-
 - PHP fallback template now includes the collapsible API Verification Secret section matching the Twig template
 - All four API endpoints (`/validate`, `/status`, `/activate`, `/update-check`) now include signature headers when `WC_LICENSE_SERVER_SECRET` is configured
 - Client library v0.2.2 verified compatible with server implementation
+
+**Release v0.7.1:**
+
+- Created release package: `releases/wc-licensed-product-0.7.1.zip` (886 KB)
+- SHA256: `6ffd0bdf47395436bbc28a029eff4c6d065f2b5b64c687b96ae36a74c3ee34ef`
+- Tagged as `v0.7.1` and pushed to `main` branch
+
+### 2026-01-29 - Version 0.7.2 - Git Submodule & CI/CD Pipeline
+
+**Overview:**
+
+Infrastructure release converting the client library dependency to a git submodule and implementing automated CI/CD releases via Gitea Actions.
+
+**Git Submodule Migration:**
+
+- Converted `magdev/wc-licensed-product-client` from Composer VCS dependency to git submodule
+- Submodule located at `lib/wc-licensed-product-client`
+- Composer uses `path` type repository pointing to local submodule
+- Symlinked to `vendor/magdev/wc-licensed-product-client` during `composer install`
+
+**Gitea CI/CD Pipeline:**
+
+- New workflow at `.gitea/workflows/release.yml`
+- Triggers on version tags (`v*`)
+- Automated steps:
+  - Checkout with recursive submodules
+  - PHP 8.3 setup with required extensions
+  - Composer dependency installation (production only)
+  - Translation compilation (`.po` to `.mo`)
+  - Version verification against plugin header
+  - Release package creation with proper exclusions
+  - SHA256 checksum generation
+  - Package structure verification
+  - Changelog extraction for release notes
+  - Gitea release creation with asset upload
+  - Pre-release detection for hyphenated tags
+
+**New files:**
+
+- `.gitea/workflows/release.yml` - Gitea Actions workflow for automated releases
+- `.gitmodules` - Git submodule configuration (created by git)
+
+**Modified files:**
+
+- `composer.json` - Changed repository type from `vcs` to `path`, URL to `lib/wc-licensed-product-client`
+- `CHANGELOG.md` - Added v0.7.2 release notes
+- `CLAUDE.md` - Removed v0.7.2 from roadmap, added session history
+
+**Package Exclusions:**
+
+Release packages exclude: `.git/`, `.gitea/`, `.gitmodules`, `lib/` (submodule source), `vendor/**/.git`, `tests/`, `CLAUDE.md`, `*.po~`, `wp-core`, `wp-plugins`, `composer.lock`
+
+**Developer Workflow Changes:**
+
+After cloning the repository, developers must now run:
+
+```bash
+git submodule update --init --recursive
+composer install
+```
+
+**Technical notes:**
+
+- Path repository uses `*` version constraint with `symlink: false` option
+- CI replaces symlink with actual files via `cp -r` before packaging
+- CI uses `actions/checkout@v4` with `submodules: recursive` for proper submodule initialization
+- Release creation uses direct Gitea API calls (`/api/v1/repos/.../releases`)
+- Requires `SRC_GITEA_TOKEN` secret configured in Gitea repository settings
+- Workflow completed successfully: 57 seconds, all checks passed
+
+**Release v0.7.2:**
+
+- Automatically created by Gitea Actions CI/CD pipeline
+- Release package: 881 KiB with SHA256 checksum
+- First automated release - all future releases will use this workflow
+
+**Additional fixes (same session):**
+
+- Updated README.md with Auto-Updates section and Development section
+- Fixed CI/CD workflow to handle existing releases (delete before recreate)
+- When updating a tag, the workflow now checks for existing releases and deletes them first
+
+**Lessons learned:**
+
+- Gitea releases persist even when their tag is deleted - must delete release via API
+- Composer `symlink: false` doesn't always work - CI must manually replace symlinks with `cp -r`
+- Never create zip archives locally on this machine (fills up RAM indefinitely)
+- Gitea API endpoint for releases by tag: `GET /api/v1/repos/{owner}/{repo}/releases/tags/{tag}`
+
+### 2026-02-01 - Bug Fix: API Verification Secret Not Visible
+
+**Overview:**
+
+Fixed the "API Verification Secret" (customer secret) not appearing on the customer account licenses page in Docker environments.
+
+**Root Cause:**
+
+The `WC_LICENSE_SERVER_SECRET` constant was not being defined even though the environment variable was set. In Docker WordPress setups using `wp-config-docker.php`, the `getenv_docker()` function retrieves values from environment variables, but the constant wasn't being created properly. The plugin was only checking for the PHP constant, not the environment variable directly.
+
+**Fix:**
+
+Added `ResponseSigner::getServerSecret()` static method that checks multiple sources for the server secret:
+
+1. `WC_LICENSE_SERVER_SECRET` constant (standard WordPress configuration)
+2. `getenv('WC_LICENSE_SERVER_SECRET')` (Docker environments)
+3. `$_ENV['WC_LICENSE_SERVER_SECRET']` (some PHP configurations)
+4. `$_SERVER['WC_LICENSE_SERVER_SECRET']` (fallback)
+
+**Modified files:**
+
+- `src/Api/ResponseSigner.php` - Added `getServerSecret()` method, updated `isSigningEnabled()` and `getCustomerSecretForLicense()` to use it
+- `src/Plugin.php` - Updated to use `ResponseSigner::isSigningEnabled()` instead of direct constant check
+
+**Technical notes:**
+
+- The fix maintains backward compatibility with standard WordPress installations using constants
+- Docker environments can now use environment variables directly without needing the constant to be defined
+- All three methods (`isSigningEnabled()`, `getCustomerSecretForLicense()`, and constructor) now use the centralized `getServerSecret()` method
+
+### 2026-02-03 - Version 0.7.4 - Prometheus Metrics Integration
+
+**Overview:**
+
+Added Prometheus metrics integration to expose license and API metrics for monitoring. Requires the WP Prometheus plugin.
+
+**New files:**
+
+- `src/Metrics/PrometheusController.php` - Prometheus metrics collection controller
+
+**Implemented:**
+
+- New "Metrics" settings section with enable/disable toggle
+- Hooks into `wp_prometheus_collect_metrics` action for metric collection
+- License gauges using existing `LicenseManager::getStatistics()`:
+  - `wclp_licenses_total{status}` - License counts by status
+  - `wclp_licenses_lifetime_total` - Lifetime licenses count
+  - `wclp_licenses_expiring_total` - Expiring licenses count
+  - `wclp_licenses_expiring_soon` - Licenses expiring within 30 days
+- Download gauges using existing `VersionManager::getDownloadStatistics()`:
+  - `wclp_downloads_total` - Total downloads
+  - `wclp_versions_active_total` - Active product versions
+- API counters (stored in WordPress options for persistence):
+  - `wclp_api_requests_total{endpoint,result}` - API requests by endpoint and result
+  - `wclp_rate_limit_exceeded_total{endpoint}` - Rate limit exceeded events
+  - `wclp_validation_errors_total{error_type}` - Validation errors by type
+
+**Modified files:**
+
+- `src/Admin/SettingsController.php` - Added 'metrics' section with settings
+- `src/Api/RestApiController.php` - Added metric tracking for API requests
+- `src/Api/UpdateController.php` - Added metric tracking for update-check requests
+- `src/Plugin.php` - Initialize PrometheusController
+
+**Technical notes:**
+
+- Metrics are only collected when enabled via settings toggle
+- Static methods allow increment from API controllers without dependency injection
+- Counter values persist across requests via `wclp_prometheus_counters` option
+- Gauges query database on each metric collection (uses existing statistics methods)
+
+### 2026-02-03 - Grafana Dashboard & WP Prometheus Integration
+
+**Overview:**
+
+Added example Grafana dashboard JSON and integrated with wp-prometheus dashboard registration system.
+
+**New files:**
+
+- `docs/grafana-dashboard.json` - Complete Grafana dashboard with 24 panels
+- `docs/grafana-dashboard.md` - Installation and usage documentation
+
+**Dashboard panels:**
+
+- License Overview: Total, Active, Lifetime, Expiring Soon, Expired, Revoked stats + pie chart + time series
+- Downloads & Versions: Total downloads, active versions, download trends
+- API Metrics: Request rates by endpoint/result, pie chart breakdown, top requests table
+- Errors & Rate Limiting: Rate limit events, validation errors by type over time
+
+**WP Prometheus integration:**
+
+- Dashboard automatically registered via `wp_prometheus_register_dashboards` hook
+- Appears in Settings > WP Prometheus > Dashboards tab when metrics are enabled
+- Uses file-based registration with metadata (title, description, icon, plugin attribution)
+
+**Modified files:**
+
+- `src/Metrics/PrometheusController.php` - Added `registerDashboard()` method and hook registration
+- `docs/grafana-dashboard.md` - Added wp-prometheus installation option as recommended method
+- `README.md` - Added "Monitoring with Prometheus & Grafana" section linking to dashboard docs
+
+**Technical notes:**
+
+- Dashboard registration only occurs when metrics are enabled (same condition as metric collection)
+- Uses `dashicons-admin-network` icon for dashboard list
+- File path uses `WC_LICENSED_PRODUCT_PLUGIN_DIR` constant for reliable path resolution
--- a/README.md
+++ b/README.md
@@ -25,6 +25,8 @@ WC Licensed Product adds a new product type "Licensed Product" to WooCommerce, e
 - **Trusted Proxy Support**: Configurable trusted proxies for accurate rate limiting behind CDNs
 - **Checkout Blocks**: Full support for WooCommerce Checkout Blocks (default since WC 8.3+)
 - **Self-Licensing**: The plugin can validate its own license (for commercial distribution)
+- **WordPress Auto-Updates**: Receive plugin updates through WordPress's native update system
+- **Automated Releases**: CI/CD pipeline for consistent release packaging

 ### Customer Features

@@ -340,6 +342,41 @@ Content-Type: application/json
 | `max_activations_reached` | Maximum activations reached |
 | `rate_limit_exceeded` | Too many requests (wait and retry) |

+## Auto-Updates
+
+Licensed plugins can receive updates through WordPress's native plugin update system. When properly configured, WordPress will check the license server for updates and display them in the Plugins page.
+
+### Configuration
+
+In WooCommerce > Settings > Licensed Products > Auto-Updates:
+
+- **Enable Update Notifications**: Show available updates in WordPress admin
+- **Automatically Install Updates**: Let WordPress install updates automatically
+- **Update Check Frequency**: How often to check for updates (1-168 hours)
+
+### How It Works
+
+1. The plugin periodically checks the configured license server for updates
+2. If a newer version is available and the license is valid, WordPress shows the update
+3. Updates can be installed manually or automatically (if enabled)
+4. Downloads are authenticated using the license key
+
+### API Endpoint
+
+The update check uses the `/update-check` REST API endpoint:
+
+```http
+POST /wp-json/wc-licensed-product/v1/update-check
+Content-Type: application/json
+
+{
+  "license_key": "XXXX-XXXX-XXXX-XXXX",
+  "domain": "example.com",
+  "plugin_slug": "my-plugin",
+  "current_version": "1.0.0"
+}
+```
+
 ## License Statuses

 - **Active**: License is valid and usable
@@ -356,6 +393,38 @@ The plugin sends automatic email notifications (configurable via WooCommerce > S
 - **Expiration Warning (1 day)**: Urgent reminder sent 1 day before expiration
 - **License Expired**: Notification when a license auto-expires

+## Monitoring with Prometheus & Grafana
+
+The plugin integrates with [wp-prometheus](https://src.bundespruefstelle.ch/magdev/wp-prometheus) to expose metrics for monitoring and alerting.
+
+### Enable Metrics
+
+1. Install and configure the wp-prometheus plugin
+2. Go to WooCommerce > Settings > Licensed Products > Metrics
+3. Enable "Prometheus Metrics"
+
+### Available Metrics
+
+**Gauges:**
+
+- `wclp_licenses_total{status}` - License counts by status
+- `wclp_licenses_lifetime_total` - Lifetime licenses
+- `wclp_licenses_expiring_soon` - Licenses expiring within 30 days
+- `wclp_downloads_total` - Total file downloads
+- `wclp_versions_active_total` - Active product versions
+
+**Counters:**
+
+- `wclp_api_requests_total{endpoint,result}` - API requests by endpoint and result
+- `wclp_rate_limit_exceeded_total{endpoint}` - Rate limit events
+- `wclp_validation_errors_total{error_type}` - Validation errors by type
+
+### Grafana Dashboard
+
+An example Grafana dashboard is included at [docs/grafana-dashboard.json](docs/grafana-dashboard.json).
+
+See [docs/grafana-dashboard.md](docs/grafana-dashboard.md) for installation instructions, panel descriptions, and alerting examples.
+
 ## Changelog

 See [CHANGELOG.md](CHANGELOG.md) for version history and changes.
@@ -369,6 +438,60 @@ For issues and feature requests, please visit:

 Marco Graetsch

+## Development
+
+### Setup
+
+After cloning the repository, initialize the git submodule and install dependencies:
+
+```bash
+git clone https://src.bundespruefstelle.ch/magdev/wc-licensed-product.git
+cd wc-licensed-product
+git submodule update --init --recursive
+composer install
+```
+
+### Project Structure
+
+- `src/` - PHP source files (PSR-4 autoloaded)
+- `assets/` - CSS and JavaScript files
+- `templates/` - Twig templates for admin and frontend views
+- `languages/` - Translation files (.pot, .po, .mo)
+- `lib/` - Git submodule for the client library
+- `docs/` - API documentation and client examples
+
+### Creating Releases
+
+Releases are automatically created by the Gitea CI/CD pipeline when a version tag is pushed:
+
+```bash
+# Update version in wc-licensed-product.php (both header and constant)
+# Update CHANGELOG.md with release notes
+git add -A && git commit -m "Release v0.7.3"
+git tag -a v0.7.3 -m "Release v0.7.3"
+git push origin main --tags
+```
+
+The pipeline will:
+
+1. Build production dependencies
+2. Compile translations
+3. Create the release package with proper WordPress structure
+4. Generate SHA256 checksum
+5. Publish to Gitea releases
+
+### Translations
+
+To add or update translations:
+
+```bash
+# Extract strings to .pot template
+# (Use a tool like wp-cli or poedit)
+
+# Compile .po files to .mo for production
+for po in languages/*.po; do msgfmt -o "${po%.po}.mo" "$po"; done
+```
+
 ## License

 GPL-2.0-or-later
--- a/composer.json
+++ b/composer.json
@@ -12,14 +12,17 @@
    ],
    "repositories": [
        {
-            "type": "vcs",
-            "url": "https://src.bundespruefstelle.ch/magdev/wc-licensed-product-client.git"
+            "type": "path",
+            "url": "lib/wc-licensed-product-client",
+            "options": {
+                "symlink": false
+            }
        }
    ],
    "require": {
        "php": ">=8.3.0",
        "twig/twig": "^3.0",
-        "magdev/wc-licensed-product-client": "dev-main"
+        "magdev/wc-licensed-product-client": "*"
    },
    "autoload": {
        "psr-4": {
--- a/composer.lock
+++ b/composer.lock
@@ -4,15 +4,15 @@
        "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
        "This file is @generated automatically"
    ],
-    "content-hash": "05af8ab515abe7e689c610724b54e27a",
+    "content-hash": "f13b7ed9531068d0180f28adc8a80397",
    "packages": [
        {
            "name": "magdev/wc-licensed-product-client",
            "version": "dev-main",
-            "source": {
-                "type": "git",
-                "url": "https://src.bundespruefstelle.ch/magdev/wc-licensed-product-client.git",
-                "reference": "56abe8a97c72419c07a6daf263ba6f4a9b5fe4b1"
+            "dist": {
+                "type": "path",
+                "url": "lib/wc-licensed-product-client",
+                "reference": "f9281ec5fb23bf1993ab0240e0347c835009a10f"
            },
            "require": {
                "php": "^8.3",
@@ -24,7 +24,6 @@
            "require-dev": {
                "phpunit/phpunit": "^11.0"
            },
-            "default-branch": true,
            "type": "library",
            "autoload": {
                "psr-4": {
@@ -52,7 +51,9 @@
                "issues": "https://src.bundespruefstelle.ch/magdev/wc-licensed-product-client/issues",
                "source": "https://src.bundespruefstelle.ch/magdev/wc-licensed-product-client"
            },
-            "time": "2026-01-28T10:56:47+00:00"
+            "transport-options": {
+                "relative": true
+            }
        },
        {
            "name": "psr/cache",
--- a/docs/grafana-dashboard.json
+++ b/docs/grafana-dashboard.json
--- a/docs/grafana-dashboard.md
+++ b/docs/grafana-dashboard.md
@@ -0,0 +1,219 @@
+# Grafana Dashboard for WC Licensed Product
+
+This dashboard provides comprehensive monitoring for the WC Licensed Product plugin using Prometheus metrics exposed via the [wp-prometheus](https://src.bundespruefstelle.ch/magdev/wp-prometheus) plugin.
+
+## Prerequisites
+
+1. **WP Prometheus Plugin** - Install and configure [wp-prometheus](https://src.bundespruefstelle.ch/magdev/wp-prometheus) on your WordPress site
+2. **Prometheus** - Configure Prometheus to scrape your WordPress metrics endpoint
+3. **Grafana** - Grafana 9.0+ with Prometheus data source configured
+4. **Enable Metrics** - In WordPress admin: WooCommerce > Settings > Licensed Products > Metrics > Enable Prometheus Metrics
+
+## Installation
+
+### Option 1: Via WP Prometheus Settings (Recommended)
+
+When metrics are enabled, the dashboard is automatically registered with wp-prometheus:
+
+1. Go to **Settings > WP Prometheus** in WordPress admin
+2. Navigate to the **Dashboards** tab
+3. Find "WC Licensed Product - License Metrics" in the list
+4. Click **Download JSON** to get the dashboard file
+5. Import the downloaded file into Grafana
+
+### Option 2: Manual Import
+
+1. Open Grafana and navigate to **Dashboards > Import**
+2. Upload the `grafana-dashboard.json` file or paste its contents
+3. Select your Prometheus data source
+4. Click **Import**
+
+### Configure Variables
+
+The dashboard includes two template variables:
+
+- **datasource** - Select your Prometheus data source
+- **instance** - Filter by WordPress instance (useful for multi-site monitoring)
+
+## Dashboard Panels
+
+### License Overview
+
+| Panel | Description |
+| --- | --- |
+| Total Licenses | Total count of all licenses |
+| Active Licenses | Licenses with `status=active` |
+| Lifetime Licenses | Licenses without expiration date |
+| Expiring Soon (30d) | Licenses expiring within 30 days |
+| Expired Licenses | Licenses with `status=expired` |
+| Revoked Licenses | Licenses with `status=revoked` |
+| Licenses by Status | Pie chart showing distribution |
+| License Status Over Time | Time series of license counts |
+
+### Downloads & Versions
+
+| Panel | Description |
+| --- | --- |
+| Total Downloads | Cumulative download count |
+| Active Product Versions | Number of active versions |
+| Downloads Over Time | Download trend graph |
+| Downloads (Selected Range) | Downloads in selected time range |
+
+### API Metrics
+
+| Panel | Description |
+| --- | --- |
+| API Requests (5m intervals) | Stacked bar chart by endpoint/result |
+| Requests by Endpoint | Donut chart of endpoint distribution |
+| Top API Requests | Table of most frequent requests |
+
+### Errors & Rate Limiting
+
+| Panel | Description |
+| --- | --- |
+| Rate Limit Events (Total) | Total HTTP 429 responses |
+| Validation Errors (Total) | Total validation failures |
+| Validation Errors Over Time | Error trend by type |
+| Validation Errors by Type | Pie chart breakdown |
+| Rate Limit Events by Endpoint | Rate limits per endpoint |
+
+## Metrics Reference
+
+### Gauges (current values)
+
+```promql
+# Licenses by status
+wclp_licenses_total{status="active|expired|revoked|inactive"}
+
+# Lifetime licenses (no expiration)
+wclp_licenses_lifetime_total
+
+# Licenses with expiration date
+wclp_licenses_expiring_total
+
+# Licenses expiring within 30 days
+wclp_licenses_expiring_soon
+
+# Total downloads
+wclp_downloads_total
+
+# Active product versions
+wclp_versions_active_total
+```
+
+### Counters (cumulative)
+
+```promql
+# API requests by endpoint and result
+wclp_api_requests_total{endpoint="validate|status|activate|update-check", result="success|error"}
+
+# Rate limit exceeded events
+wclp_rate_limit_exceeded_total{endpoint="validate|status|activate|update-check"}
+
+# Validation errors by type
+wclp_validation_errors_total{error_type="license_not_found|domain_mismatch|license_expired|license_revoked|..."}
+```
+
+## Example Prometheus Queries
+
+### Success Rate
+
+```promql
+sum(rate(wclp_api_requests_total{result="success"}[5m])) /
+sum(rate(wclp_api_requests_total[5m])) * 100
+```
+
+### Error Rate by Endpoint
+
+```promql
+sum by (endpoint) (rate(wclp_api_requests_total{result="error"}[5m]))
+```
+
+### License Churn (new activations)
+
+```promql
+increase(wclp_licenses_total{status="active"}[1d])
+```
+
+### Top Validation Errors
+
+```promql
+topk(5, sum by (error_type) (wclp_validation_errors_total))
+```
+
+## Alerting Examples
+
+Add these alerts to your Prometheus alerting rules:
+
+```yaml
+groups:
+  - name: wc-licensed-product
+    rules:
+      # High rate limit events
+      - alert: HighRateLimitEvents
+        expr: increase(wclp_rate_limit_exceeded_total[5m]) > 10
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "High rate limiting on {{ $labels.endpoint }}"
+
+      # Many expiring licenses
+      - alert: LicensesExpiringSoon
+        expr: wclp_licenses_expiring_soon > 20
+        for: 1h
+        labels:
+          severity: info
+        annotations:
+          summary: "{{ $value }} licenses expiring within 30 days"
+
+      # API error rate
+      - alert: HighAPIErrorRate
+        expr: |
+          sum(rate(wclp_api_requests_total{result="error"}[5m])) /
+          sum(rate(wclp_api_requests_total[5m])) > 0.1
+        for: 10m
+        labels:
+          severity: warning
+        annotations:
+          summary: "API error rate above 10%"
+```
+
+## Prometheus Configuration
+
+Add to your `prometheus.yml`:
+
+```yaml
+scrape_configs:
+  - job_name: 'wordpress'
+    metrics_path: '/metrics'
+    scheme: https
+    bearer_token: 'YOUR_WP_PROMETHEUS_TOKEN'
+    static_configs:
+      - targets: ['your-wordpress-site.com']
+```
+
+## Troubleshooting
+
+### No data showing
+
+1. Verify wp-prometheus is installed and configured
+2. Check that metrics are enabled in WC Licensed Product settings
+3. Confirm Prometheus can reach your WordPress metrics endpoint
+4. Check the data source selection in Grafana
+
+### Missing metrics
+
+Some metrics only appear after relevant actions occur:
+
+- `wclp_api_requests_total` - After API requests
+- `wclp_rate_limit_exceeded_total` - After rate limit events
+- `wclp_validation_errors_total` - After validation errors
+
+### Counter resets
+
+Counters persist in WordPress options and survive restarts. To reset:
+
+```php
+\Jeremias\WcLicensedProduct\Metrics\PrometheusController::resetCounters();
+```
--- a/languages/wc-licensed-product-de_CH.mo
+++ b/languages/wc-licensed-product-de_CH.mo
--- a/languages/wc-licensed-product-de_CH.po
+++ b/languages/wc-licensed-product-de_CH.po
--- a/languages/wc-licensed-product.pot
+++ b/languages/wc-licensed-product.pot
--- a/lib/wc-licensed-product-client
+++ b/lib/wc-licensed-product-client
--- a/releases/wc-licensed-product-0.7.1.zip
+++ b/releases/wc-licensed-product-0.7.1.zip
--- a/releases/wc-licensed-product-0.7.1.zip.sha256
+++ b/releases/wc-licensed-product-0.7.1.zip.sha256
@@ -0,0 +1 @@
+6ffd0bdf47395436bbc28a029eff4c6d065f2b5b64c687b96ae36a74c3ee34ef  wc-licensed-product-0.7.1.zip
--- a/src/Admin/SettingsController.php
+++ b/src/Admin/SettingsController.php
@@ -65,6 +65,7 @@ final class SettingsController
            'auto-updates' => __('Auto-Updates', 'wc-licensed-product'),
            'defaults' => __('Default Settings', 'wc-licensed-product'),
            'notifications' => __('Notifications', 'wc-licensed-product'),
+            'metrics' => __('Metrics', 'wc-licensed-product'),
        ];
    }

@@ -116,6 +117,7 @@ final class SettingsController
            'auto-updates' => $this->getAutoUpdatesSettings(),
            'defaults' => $this->getDefaultsSettings(),
            'notifications' => $this->getNotificationsSettings(),
+            'metrics' => $this->getMetricsSettings(),
            default => $this->getPluginLicenseSettings(),
        };
    }
@@ -314,6 +316,32 @@ final class SettingsController
        ];
    }

+    /**
+     * Get metrics settings
+     */
+    private function getMetricsSettings(): array
+    {
+        return [
+            'metrics_section_title' => [
+                'name' => __('Prometheus Metrics', 'wc-licensed-product'),
+                'type' => 'title',
+                'desc' => __('Expose license and API metrics for Prometheus monitoring. Requires the WP Prometheus plugin to be installed and active.', 'wc-licensed-product'),
+                'id' => 'wc_licensed_product_section_metrics',
+            ],
+            'metrics_enabled' => [
+                'name' => __('Enable Prometheus Metrics', 'wc-licensed-product'),
+                'type' => 'checkbox',
+                'desc' => __('Expose license statistics, API usage, and download metrics via Prometheus.', 'wc-licensed-product'),
+                'id' => 'wc_licensed_product_metrics_enabled',
+                'default' => 'no',
+            ],
+            'metrics_section_end' => [
+                'type' => 'sectionend',
+                'id' => 'wc_licensed_product_section_metrics_end',
+            ],
+        ];
+    }
+
    /**
     * Render settings tab content
     */
@@ -575,4 +603,12 @@ final class SettingsController
            wp_send_json_error(['message' => $error]);
        }
    }
+
+    /**
+     * Check if Prometheus metrics are enabled
+     */
+    public static function isMetricsEnabled(): bool
+    {
+        return get_option('wc_licensed_product_metrics_enabled', 'no') === 'yes';
+    }
 }
--- a/src/Api/ResponseSigner.php
+++ b/src/Api/ResponseSigner.php
@@ -26,9 +26,7 @@ final class ResponseSigner

    public function __construct()
    {
-        $this->serverSecret = defined('WC_LICENSE_SERVER_SECRET')
-            ? WC_LICENSE_SERVER_SECRET
-            : '';
+        $this->serverSecret = self::getServerSecret();
    }

    /**
@@ -185,7 +183,7 @@ final class ResponseSigner
     */
    public static function getCustomerSecretForLicense(string $licenseKey): ?string
    {
-        $serverSecret = defined('WC_LICENSE_SERVER_SECRET') ? WC_LICENSE_SERVER_SECRET : '';
+        $serverSecret = self::getServerSecret();

        if (empty($serverSecret)) {
            return null;
@@ -201,6 +199,40 @@ final class ResponseSigner
     */
    public static function isSigningEnabled(): bool
    {
-        return defined('WC_LICENSE_SERVER_SECRET') && !empty(WC_LICENSE_SERVER_SECRET);
+        return !empty(self::getServerSecret());
+    }
+
+    /**
+     * Get the server secret from constant or environment variable
+     *
+     * Checks in order:
+     * 1. WC_LICENSE_SERVER_SECRET constant (preferred)
+     * 2. WC_LICENSE_SERVER_SECRET environment variable (Docker fallback)
+     *
+     * @return string The server secret, or empty string if not configured
+     */
+    public static function getServerSecret(): string
+    {
+        // First check the constant (standard WordPress configuration)
+        if (defined('WC_LICENSE_SERVER_SECRET') && !empty(WC_LICENSE_SERVER_SECRET)) {
+            return WC_LICENSE_SERVER_SECRET;
+        }
+
+        // Fallback to environment variable (Docker environments)
+        $envSecret = getenv('WC_LICENSE_SERVER_SECRET');
+        if ($envSecret !== false && !empty($envSecret)) {
+            return $envSecret;
+        }
+
+        // Also check $_ENV and $_SERVER (some PHP configurations)
+        if (!empty($_ENV['WC_LICENSE_SERVER_SECRET'])) {
+            return $_ENV['WC_LICENSE_SERVER_SECRET'];
+        }
+
+        if (!empty($_SERVER['WC_LICENSE_SERVER_SECRET'])) {
+            return $_SERVER['WC_LICENSE_SERVER_SECRET'];
+        }
+
+        return '';
    }
 }
--- a/src/Api/RestApiController.php
+++ b/src/Api/RestApiController.php
@@ -10,6 +10,7 @@ declare(strict_types=1);
 namespace Jeremias\WcLicensedProduct\Api;

 use Jeremias\WcLicensedProduct\License\LicenseManager;
+use Jeremias\WcLicensedProduct\Metrics\PrometheusController;
 use WP_REST_Request;
 use WP_REST_Response;
 use WP_REST_Server;
@@ -108,6 +109,10 @@ final class RestApiController
                'retry_after' => $retryAfter,
            ], 429);
            $response->header('Retry-After', (string) $retryAfter);
+
+            // Track rate limit event for metrics
+            PrometheusController::incrementRateLimitExceeded('api');
+
            return $response;
        }

@@ -209,6 +214,16 @@ final class RestApiController

        $statusCode = $this->getStatusCodeForResult($result);

+        // Track metrics
+        if ($result['valid']) {
+            PrometheusController::incrementApiRequest('validate', 'success');
+        } else {
+            PrometheusController::incrementApiRequest('validate', 'error');
+            if (!empty($result['error'])) {
+                PrometheusController::incrementValidationError($result['error']);
+            }
+        }
+
        return new WP_REST_Response($result, $statusCode);
    }

@@ -247,6 +262,9 @@ final class RestApiController
        $license = $this->licenseManager->getLicenseByKey($licenseKey);

        if (!$license) {
+            PrometheusController::incrementApiRequest('status', 'error');
+            PrometheusController::incrementValidationError('license_not_found');
+
            return new WP_REST_Response([
                'valid' => false,
                'error' => 'license_not_found',
@@ -254,6 +272,8 @@ final class RestApiController
            ], 404);
        }

+        PrometheusController::incrementApiRequest('status', 'success');
+
        return new WP_REST_Response([
            'valid' => $license->isValid(),
            'status' => $license->getStatus(),
@@ -280,6 +300,9 @@ final class RestApiController
        $license = $this->licenseManager->getLicenseByKey($licenseKey);

        if (!$license) {
+            PrometheusController::incrementApiRequest('activate', 'error');
+            PrometheusController::incrementValidationError('license_not_found');
+
            return new WP_REST_Response([
                'success' => false,
                'error' => 'license_not_found',
@@ -288,6 +311,9 @@ final class RestApiController
        }

        if (!$license->isValid()) {
+            PrometheusController::incrementApiRequest('activate', 'error');
+            PrometheusController::incrementValidationError('license_invalid');
+
            return new WP_REST_Response([
                'success' => false,
                'error' => 'license_invalid',
@@ -299,6 +325,8 @@ final class RestApiController

        // Check if already activated on this domain
        if ($license->getDomain() === $normalizedDomain) {
+            PrometheusController::incrementApiRequest('activate', 'success');
+
            return new WP_REST_Response([
                'success' => true,
                'message' => __('License is already activated for this domain.', 'wc-licensed-product'),
@@ -307,6 +335,9 @@ final class RestApiController

        // Check if can activate on another domain
        if (!$license->canActivate()) {
+            PrometheusController::incrementApiRequest('activate', 'error');
+            PrometheusController::incrementValidationError('max_activations_reached');
+
            return new WP_REST_Response([
                'success' => false,
                'error' => 'max_activations_reached',
@@ -318,6 +349,9 @@ final class RestApiController
        $success = $this->licenseManager->updateLicenseDomain($license->getId(), $domain);

        if (!$success) {
+            PrometheusController::incrementApiRequest('activate', 'error');
+            PrometheusController::incrementValidationError('activation_failed');
+
            return new WP_REST_Response([
                'success' => false,
                'error' => 'activation_failed',
@@ -325,6 +359,8 @@ final class RestApiController
            ], 500);
        }

+        PrometheusController::incrementApiRequest('activate', 'success');
+
        return new WP_REST_Response([
            'success' => true,
            'message' => __('License activated successfully.', 'wc-licensed-product'),
--- a/src/Api/UpdateController.php
+++ b/src/Api/UpdateController.php
@@ -12,6 +12,7 @@ declare(strict_types=1);
 namespace Jeremias\WcLicensedProduct\Api;

 use Jeremias\WcLicensedProduct\License\LicenseManager;
+use Jeremias\WcLicensedProduct\Metrics\PrometheusController;
 use Jeremias\WcLicensedProduct\Product\VersionManager;
 use Jeremias\WcLicensedProduct\Product\ProductVersion;
 use WP_REST_Request;
@@ -113,6 +114,10 @@ final class UpdateController
                'retry_after' => $retryAfter,
            ], 429);
            $response->header('Retry-After', (string) $retryAfter);
+
+            // Track rate limit event for metrics
+            PrometheusController::incrementRateLimitExceeded('update-check');
+
            return $response;
        }

@@ -179,10 +184,14 @@ final class UpdateController
        $validationResult = $this->licenseManager->validateLicense($licenseKey, $domain);

        if (!$validationResult['valid']) {
+            $errorType = $validationResult['error'] ?? 'license_invalid';
+            PrometheusController::incrementApiRequest('update-check', 'error');
+            PrometheusController::incrementValidationError($errorType);
+
            return new WP_REST_Response([
                'success' => false,
                'update_available' => false,
-                'error' => $validationResult['error'] ?? 'license_invalid',
+                'error' => $errorType,
                'message' => $validationResult['message'] ?? __('License validation failed.', 'wc-licensed-product'),
            ], $validationResult['error'] === 'license_not_found' ? 404 : 403);
        }
@@ -190,6 +199,9 @@ final class UpdateController
        // Get license to access product ID
        $license = $this->licenseManager->getLicenseByKey($licenseKey);
        if (!$license) {
+            PrometheusController::incrementApiRequest('update-check', 'error');
+            PrometheusController::incrementValidationError('license_not_found');
+
            return new WP_REST_Response([
                'success' => false,
                'update_available' => false,
@@ -202,6 +214,9 @@ final class UpdateController
        $product = wc_get_product($productId);

        if (!$product) {
+            PrometheusController::incrementApiRequest('update-check', 'error');
+            PrometheusController::incrementValidationError('product_not_found');
+
            return new WP_REST_Response([
                'success' => false,
                'update_available' => false,
@@ -214,6 +229,8 @@ final class UpdateController
        $latestVersion = $this->getLatestVersionForLicense($license);

        if (!$latestVersion) {
+            PrometheusController::incrementApiRequest('update-check', 'success');
+
            return new WP_REST_Response([
                'success' => true,
                'update_available' => false,
@@ -230,6 +247,8 @@ final class UpdateController
        // Build response
        $response = $this->buildUpdateResponse($product, $latestVersion, $license, $updateAvailable);

+        PrometheusController::incrementApiRequest('update-check', 'success');
+
        return new WP_REST_Response($response);
    }

--- a/src/Metrics/PrometheusController.php
+++ b/src/Metrics/PrometheusController.php
@@ -0,0 +1,282 @@
+<?php
+/**
+ * Prometheus Metrics Controller
+ *
+ * @package Jeremias\WcLicensedProduct\Metrics
+ */
+
+declare(strict_types=1);
+
+namespace Jeremias\WcLicensedProduct\Metrics;
+
+use Jeremias\WcLicensedProduct\Admin\SettingsController;
+use Jeremias\WcLicensedProduct\License\LicenseManager;
+use Jeremias\WcLicensedProduct\Product\VersionManager;
+
+/**
+ * Exposes license and API metrics for Prometheus monitoring
+ */
+final class PrometheusController
+{
+    /**
+     * Option name for storing API counters
+     */
+    private const COUNTERS_OPTION = 'wclp_prometheus_counters';
+
+    private LicenseManager $licenseManager;
+    private VersionManager $versionManager;
+
+    public function __construct(LicenseManager $licenseManager, VersionManager $versionManager)
+    {
+        $this->licenseManager = $licenseManager;
+        $this->versionManager = $versionManager;
+    }
+
+    /**
+     * Register hooks for Prometheus metrics collection
+     */
+    public function register(): void
+    {
+        // Only register if metrics are enabled
+        if (!SettingsController::isMetricsEnabled()) {
+            return;
+        }
+
+        add_action('wp_prometheus_collect_metrics', [$this, 'collectMetrics']);
+        add_action('wp_prometheus_register_dashboards', [$this, 'registerDashboard']);
+    }
+
+    /**
+     * Register Grafana dashboard with wp-prometheus
+     *
+     * @param object $provider The dashboard provider object
+     */
+    public function registerDashboard(object $provider): void
+    {
+        $dashboardFile = WC_LICENSED_PRODUCT_PLUGIN_DIR . 'docs/grafana-dashboard.json';
+
+        if (!file_exists($dashboardFile)) {
+            return;
+        }
+
+        $provider->register_dashboard('wc-licensed-product', [
+            'title'       => __('WC Licensed Product - License Metrics', 'wc-licensed-product'),
+            'description' => __('Monitor license status, downloads, API usage, and validation errors.', 'wc-licensed-product'),
+            'icon'        => 'dashicons-admin-network',
+            'file'        => $dashboardFile,
+            'plugin'      => 'WC Licensed Product',
+        ]);
+    }
+
+    /**
+     * Collect and register all metrics
+     *
+     * @param object $collector The Prometheus collector object
+     */
+    public function collectMetrics(object $collector): void
+    {
+        $this->collectLicenseMetrics($collector);
+        $this->collectDownloadMetrics($collector);
+        $this->collectApiMetrics($collector);
+    }
+
+    /**
+     * Collect license-related metrics
+     */
+    private function collectLicenseMetrics(object $collector): void
+    {
+        $stats = $this->licenseManager->getStatistics();
+
+        // License count by status (gauge)
+        $licensesByStatus = $collector->register_gauge(
+            'wclp_licenses_total',
+            'Total number of licenses by status',
+            ['status']
+        );
+
+        foreach ($stats['by_status'] as $status => $count) {
+            $licensesByStatus->set($count, [$status]);
+        }
+
+        // Lifetime licenses (gauge)
+        $lifetimeLicenses = $collector->register_gauge(
+            'wclp_licenses_lifetime_total',
+            'Total number of lifetime licenses'
+        );
+        $lifetimeLicenses->set($stats['lifetime']);
+
+        // Expiring licenses (gauge)
+        $expiringLicenses = $collector->register_gauge(
+            'wclp_licenses_expiring_total',
+            'Total number of licenses with expiration date'
+        );
+        $expiringLicenses->set($stats['expiring']);
+
+        // Licenses expiring soon - next 30 days (gauge)
+        $expiringSoon = $collector->register_gauge(
+            'wclp_licenses_expiring_soon',
+            'Licenses expiring within 30 days'
+        );
+        $expiringSoon->set($stats['expiring_soon']);
+    }
+
+    /**
+     * Collect download-related metrics
+     */
+    private function collectDownloadMetrics(object $collector): void
+    {
+        $stats = $this->versionManager->getDownloadStatistics();
+
+        // Total downloads (gauge)
+        $totalDownloads = $collector->register_gauge(
+            'wclp_downloads_total',
+            'Total number of file downloads'
+        );
+        $totalDownloads->set($stats['total']);
+
+        // Active versions count (gauge)
+        $activeVersions = $collector->register_gauge(
+            'wclp_versions_active_total',
+            'Total number of active product versions'
+        );
+        $activeVersions->set($this->countActiveVersions());
+    }
+
+    /**
+     * Collect API-related metrics (counters)
+     */
+    private function collectApiMetrics(object $collector): void
+    {
+        $counters = $this->getCounters();
+
+        // API requests by endpoint and result (counter)
+        $apiRequests = $collector->register_counter(
+            'wclp_api_requests_total',
+            'Total API requests by endpoint and result',
+            ['endpoint', 'result']
+        );
+
+        foreach ($counters['api_requests'] ?? [] as $key => $count) {
+            [$endpoint, $result] = explode(':', $key);
+            $apiRequests->incBy($count, [$endpoint, $result]);
+        }
+
+        // Rate limit exceeded events (counter)
+        $rateLimitExceeded = $collector->register_counter(
+            'wclp_rate_limit_exceeded_total',
+            'Total rate limit exceeded events by endpoint',
+            ['endpoint']
+        );
+
+        foreach ($counters['rate_limit'] ?? [] as $endpoint => $count) {
+            $rateLimitExceeded->incBy($count, [$endpoint]);
+        }
+
+        // Validation errors by type (counter)
+        $validationErrors = $collector->register_counter(
+            'wclp_validation_errors_total',
+            'Total validation errors by error type',
+            ['error_type']
+        );
+
+        foreach ($counters['validation_errors'] ?? [] as $errorType => $count) {
+            $validationErrors->incBy($count, [$errorType]);
+        }
+    }
+
+    /**
+     * Count active product versions
+     */
+    private function countActiveVersions(): int
+    {
+        global $wpdb;
+
+        $tableName = \Jeremias\WcLicensedProduct\Installer::getVersionsTable();
+
+        return (int) $wpdb->get_var(
+            "SELECT COUNT(*) FROM {$tableName} WHERE is_active = 1"
+        );
+    }
+
+    /**
+     * Get stored counters
+     */
+    private function getCounters(): array
+    {
+        $counters = get_option(self::COUNTERS_OPTION, []);
+        return is_array($counters) ? $counters : [];
+    }
+
+    /**
+     * Increment an API request counter
+     *
+     * @param string $endpoint The API endpoint (validate, status, activate, update-check)
+     * @param string $result The result (success or error)
+     */
+    public static function incrementApiRequest(string $endpoint, string $result): void
+    {
+        if (!SettingsController::isMetricsEnabled()) {
+            return;
+        }
+
+        $counters = get_option(self::COUNTERS_OPTION, []);
+        if (!is_array($counters)) {
+            $counters = [];
+        }
+
+        $key = "{$endpoint}:{$result}";
+        $counters['api_requests'][$key] = ($counters['api_requests'][$key] ?? 0) + 1;
+
+        update_option(self::COUNTERS_OPTION, $counters, false);
+    }
+
+    /**
+     * Increment rate limit exceeded counter
+     *
+     * @param string $endpoint The API endpoint
+     */
+    public static function incrementRateLimitExceeded(string $endpoint): void
+    {
+        if (!SettingsController::isMetricsEnabled()) {
+            return;
+        }
+
+        $counters = get_option(self::COUNTERS_OPTION, []);
+        if (!is_array($counters)) {
+            $counters = [];
+        }
+
+        $counters['rate_limit'][$endpoint] = ($counters['rate_limit'][$endpoint] ?? 0) + 1;
+
+        update_option(self::COUNTERS_OPTION, $counters, false);
+    }
+
+    /**
+     * Increment validation error counter
+     *
+     * @param string $errorType The error type (license_not_found, domain_mismatch, etc.)
+     */
+    public static function incrementValidationError(string $errorType): void
+    {
+        if (!SettingsController::isMetricsEnabled()) {
+            return;
+        }
+
+        $counters = get_option(self::COUNTERS_OPTION, []);
+        if (!is_array($counters)) {
+            $counters = [];
+        }
+
+        $counters['validation_errors'][$errorType] = ($counters['validation_errors'][$errorType] ?? 0) + 1;
+
+        update_option(self::COUNTERS_OPTION, $counters, false);
+    }
+
+    /**
+     * Reset all counters (useful for testing or maintenance)
+     */
+    public static function resetCounters(): void
+    {
+        delete_option(self::COUNTERS_OPTION);
+    }
+}
--- a/src/Plugin.php
+++ b/src/Plugin.php
@@ -26,6 +26,7 @@ use Jeremias\WcLicensedProduct\Frontend\AccountController;
 use Jeremias\WcLicensedProduct\Frontend\DownloadController;
 use Jeremias\WcLicensedProduct\License\LicenseManager;
 use Jeremias\WcLicensedProduct\License\PluginLicenseChecker;
+use Jeremias\WcLicensedProduct\Metrics\PrometheusController;
 use Jeremias\WcLicensedProduct\Product\LicensedProductType;
 use Jeremias\WcLicensedProduct\Product\VersionManager;
 use Jeremias\WcLicensedProduct\Update\PluginUpdateChecker;
@@ -147,7 +148,7 @@ final class Plugin
        new LicenseEmailController($this->licenseManager);

        // Initialize response signing if server secret is configured
-        if (defined('WC_LICENSE_SERVER_SECRET') && WC_LICENSE_SERVER_SECRET !== '') {
+        if (ResponseSigner::isSigningEnabled()) {
            (new ResponseSigner())->register();
        }

@@ -171,6 +172,9 @@ final class Plugin
        if (!empty($serverUrl) && !$licenseChecker->isSelfLicensing()) {
            PluginUpdateChecker::getInstance()->register();
        }
+
+        // Initialize Prometheus metrics if enabled
+        (new PrometheusController($this->licenseManager, $this->versionManager))->register();
    }

    /**
--- a/wc-licensed-product.php
+++ b/wc-licensed-product.php
@@ -3,7 +3,7 @@
 * Plugin Name: WooCommerce Licensed Product
 * Plugin URI: https://src.bundespruefstelle.ch/magdev/wc-licensed-product
 * Description: WooCommerce plugin to sell software products using license keys with domain-based validation.
- * Version: 0.7.1
+ * Version: 0.7.5
 * Author: Marco Graetsch
 * Author URI: https://src.bundespruefstelle.ch/magdev
 * License: GPL-2.0-or-later
@@ -28,7 +28,7 @@ if (!defined('ABSPATH')) {
 }

 // Plugin constants
-define('WC_LICENSED_PRODUCT_VERSION', '0.7.1');
+define('WC_LICENSED_PRODUCT_VERSION', '0.7.5');
 define('WC_LICENSED_PRODUCT_PLUGIN_FILE', __FILE__);
 define('WC_LICENSED_PRODUCT_PLUGIN_DIR', plugin_dir_path(__FILE__));
 define('WC_LICENSED_PRODUCT_PLUGIN_URL', plugin_dir_url(__FILE__));
Author	SHA1	Message	Date
magdev	57e1b838cc	Add Grafana dashboard and wp-prometheus integration (v0.7.5) All checks were successful Create Release Package / build-release (push) Successful in 1m9s Details - Add example Grafana dashboard with 24 panels for license metrics - Register dashboard with wp-prometheus via hook - Add dashboard documentation with PromQL examples and alerting rules - Update README with monitoring section Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-02-03 11:29:14 +01:00
magdev	cfd34c9329	Add MARKETING.md to .gitignore Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-02-03 10:58:30 +01:00
magdev	fb4be7124b	Update CLAUDE.md with v0.7.4 session learnings - Removed v0.7.4 from roadmap (completed) - Added session history for Prometheus metrics integration - Documented new PrometheusController and metrics implementation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-02-03 10:57:01 +01:00
magdev	73ba7fb929	Add Prometheus metrics integration (v0.7.4) All checks were successful Create Release Package / build-release (push) Successful in 1m8s Details - New Metrics settings tab with enable/disable toggle - PrometheusController for wp_prometheus_collect_metrics hook - License gauges: total by status, lifetime, expiring, expiring soon - Download gauges: total downloads, active versions - API counters: requests, rate limits, validation errors - Metric tracking in RestApiController and UpdateController Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-02-03 10:52:50 +01:00
magdev	548b2ae8af	Bump version to 0.7.3 All checks were successful Create Release Package / build-release (push) Successful in 1m15s Details Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-02-01 13:53:37 +01:00
magdev	e0001c3f4e	Fix API Verification Secret not visible in Docker environments - Add ResponseSigner::getServerSecret() to check multiple sources - Check constant, getenv(), $_ENV, and $_SERVER for server secret - Update Plugin.php to use ResponseSigner::isSigningEnabled() - Maintains backward compatibility with standard WordPress setups Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-02-01 13:52:57 +01:00
magdev	a879be989c	Update CLAUDE.md with Docker environment variable fix session - Documented bug fix for API Verification Secret not visible in Docker - Added ResponseSigner::getServerSecret() method documentation - Removed known bug from roadmap (now fixed) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-02-01 13:51:57 +01:00
magdev	40c08bf474	Update CLAUDE.md with v0.7.2 session learnings - Document CI/CD workflow fix for handling existing releases - Add lessons learned about Gitea releases and tag updates - Note about not creating zip archives locally (RAM issue) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-29 22:44:08 +01:00
magdev	5826c744dc	Fix CI/CD workflow to handle existing releases All checks were successful Create Release Package / build-release (push) Successful in 1m1s Details Delete existing release before creating a new one when tag is updated. This prevents "Release has no Tag" error when recreating tags. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-29 22:42:22 +01:00
magdev	3a81544f30	Update README with auto-updates and development sections Some checks failed Create Release Package / build-release (push) Failing after 57s Details - Add auto-updates documentation explaining WordPress native update integration - Add development section with setup instructions and git submodule usage - Document CI/CD release process for contributors - Add core features: WordPress Auto-Updates and Automated Releases Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-29 22:40:04 +01:00
magdev	89493aa5b6	Update CLAUDE.md with accurate v0.7.2 CI/CD details Document the successful automated release workflow including: - Correct version constraint (*) and symlink handling - Direct Gitea API calls instead of gitea-release-action - Correct secret name (SRC_GITEA_TOKEN) - Workflow completion time (57 seconds) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-29 22:37:51 +01:00
magdev	46e5b5a1c5	Rewrite workflow to match working reference implementations All checks were successful Create Release Package / build-release (push) Successful in 57s Details Simplified workflow based on wp-fedistream and wc-tier-and-package-prices which have working CI/CD pipelines with same project structure. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-29 22:29:05 +01:00
magdev	b89225c6d7	Fix zip packaging directory structure Some checks failed Create Release Package / build-release (push) Failing after 1m2s Details Copy workspace to temp directory with proper subdirectory name before creating zip to ensure correct WordPress plugin structure. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-29 22:25:25 +01:00
magdev	0ebd2d0103	Add vendor directory verification and symlink fix Some checks failed Create Release Package / build-release (push) Failing after 59s Details Explicitly check vendor after composer install and replace symlink with actual files if needed for proper packaging. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-29 22:21:12 +01:00
magdev	6a10eada8c	Disable symlink for path repository in composer Some checks failed Create Release Package / build-release (push) Failing after 1m0s Details Force Composer to copy files instead of symlink so vendor/ is properly included in release package (lib/ is excluded). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-29 22:19:08 +01:00
magdev	f4da9e116a	Fix SIGPIPE error in package verification Some checks failed Create Release Package / build-release (push) Failing after 1m1s Details Add \|\| true to suppress exit code 141 from unzip piped to head. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-29 22:16:57 +01:00
magdev	601a4f6da2	Skip lock file check in composer validation Some checks failed Create Release Package / build-release (push) Failing after 1m7s Details --no-check-lock: Skip lock file validation (regenerated during install) --no-check-all: Only validate schema, not warnings Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-29 22:14:52 +01:00
magdev	0758caefc7	Fix composer validation for path repository Some checks failed Create Release Package / build-release (push) Failing after 1m0s Details - Change version constraint from @dev to * for path repository - Remove --strict from composer validate (path repos can't have proper versions) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-29 22:10:41 +01:00
magdev	bcd3481ea3	Use relative path for submodule URL Some checks failed Create Release Package / build-release (push) Failing after 1m3s Details Fixes CI/CD failing to clone submodule via HTTPS. Relative path uses same protocol/auth as parent repo. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-29 22:00:43 +01:00
magdev	60fb5cc13c	Fix Gitea release workflow to use API directly Some checks failed Create Release Package / build-release (push) Has been cancelled Details Replace non-existent actions/gitea-release-action with direct Gitea API calls using curl for release creation and asset upload. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-29 21:56:41 +01:00
magdev	1dc128a1e5	Bump version to 0.7.2 Some checks failed Create Release Package / build-release (push) Failing after 4s Details Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-29 21:53:30 +01:00
magdev	f32758ab28	Add git submodule and Gitea CI/CD pipeline for v0.7.2 - Convert wc-licensed-product-client from Composer VCS to git submodule - Add Gitea Actions workflow for automated releases on version tags - Update composer.json to use path repository for submodule - Workflow includes: submodule checkout, PHP setup, translation compilation, version verification, package creation, checksum generation, release upload Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-29 21:53:06 +01:00
magdev	ac1814cbb0	Add release package for v0.7.1 - Created wc-licensed-product-0.7.1.zip (886 KB) - SHA256: 6ffd0bdf47395436bbc28a029eff4c6d065f2b5b64c687b96ae36a74c3ee34ef - Updated CLAUDE.md with release info Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-28 12:09:25 +01:00
				`@@ -0,0 +1 @@`
				`6ffd0bdf47395436bbc28a029eff4c6d065f2b5b64c687b96ae36a74c3ee34ef wc-licensed-product-0.7.1.zip`