refactor: convert to Composer library with rate-limit mitigation

- Add composer.json with PSR-4 autoload (soderlind/wordpress-github-updater)
- Split class into src/GitHubUpdater.php and src/GitHub_Plugin_Updater.php
- Add check_period param (default 6h) and throttling (72h when update known)
- Add auth_token param for private repos / higher rate limits
- Move workflow templates to .github/workflows/
- Add .gitattributes for export-ignore
- Add CHANGELOG.md

BREAKING: Package structure changed from single file to PSR-4 layout

Author: soderlind

.gitattributes

@@ -0,0 +1,24 @@
+# Export-ignore: exclude from Composer packages / releases
+.git* export-ignore
+.github/ export-ignore
+.vscode/ export-ignore
+tests/ export-ignore
+docs/ export-ignore
+
+# Workflow templates (kept for reference, not for library users)
+manually-build-zip.yml export-ignore
+on-release-add.zip.yml export-ignore
+
+# Dev files
+phpunit.xml export-ignore
+phpunit.xml.dist export-ignore
+phpcs.xml export-ignore
+.editorconfig export-ignore
+CHANGELOG.md export-ignore
+
+# Normalize line endings
+* text=auto
+*.php text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.yml text eol=lf

manually-build-zip.yml .github/workflows/manually-build-zip.ymlmanually-build-zip.yml renamed to .github/workflows/manually-build-zip.yml

@@ -0,0 +1,43 @@
+# 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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-04-05
+
+### Added
+
+- **Composer package**: Install via `composer require soderlind/wordpress-github-updater`.
+- **Rate-limit mitigation**:
+  - Configurable `check_period` parameter (default: 6 hours).
+  - Throttled checks when update already known (72 hours).
+  - Optional `auth_token` parameter for GitHub authentication (increases rate limit from 60 to 5000 requests/hour).
+- **API error logging**: Logs GitHub API errors via `puc_api_error` hook when `WP_DEBUG` is enabled.
+- **PSR-4 autoloading**: Classes in `src/` directory.
+
+### Changed
+
+- **BREAKING**: Package structure changed from single file to PSR-4 layout (`src/GitHubUpdater.php`, `src/GitHub_Plugin_Updater.php`).
+- `GitHubUpdater::init()` signature extended with two new optional parameters: `check_period` and `auth_token`.
+- Workflow templates moved to `.github/workflows/`.
+- Default check interval reduced from 12 hours to 6 hours.
+
+### Deprecated
+
+- `GitHub_Plugin_Updater` class — use `GitHubUpdater::init()` directly.
+
+## [1.0.0] - 2024-03-01
+
+### Added
+
+- Initial release.
+- `GitHubUpdater::init()` static API.
+- `GitHub_Plugin_Updater` wrapper class with config array constructor.
+- Release asset filtering via `name_regex`.
+- Branch selection support.
+- GitHub Actions workflow templates for release builds.
+
+[2.0.0]: https://github.com/soderlind/wordpress-plugin-github-updater/compare/1.0.0...2.0.0
+[1.0.0]: https://github.com/soderlind/wordpress-plugin-github-updater/releases/tag/1.0.0

on-release-add.zip.yml .github/workflows/on-release-add.zip.ymlon-release-add.zip.yml renamed to .github/workflows/on-release-add.zip.yml

@@ -1,42 +1,44 @@
 # WordPress Plugin GitHub Updater
 
-Reusable GitHub updater helper for WordPress plugins, built on top of `yahnis-elsts/plugin-update-checker`.
+Composer library for handling WordPress plugin updates from GitHub repositories. Built on `yahnis-elsts/plugin-update-checker` with built-in rate-limit mitigation.
 
 ## Features
 
-- Automatic plugin updates from GitHub.
+- **Automatic updates** from GitHub releases or branch commits.
+- **Rate-limit mitigation**: Configurable check intervals (default 6h) and throttling (72h when update already known).
+- **GitHub token support** for private repos and higher API limits (60 → 5000 requests/hour).
 - Release-asset filtering using regex.
 - Branch selection (default: `main`).
-- Canonical static API (`GitHubUpdater::init`) plus backward-compatible wrapper (`GitHub_Plugin_Updater`).
+- Canonical static API (`GitHubUpdater::init`) plus backward-compatible wrapper.
 - Error handling with `WP_DEBUG` logging.
 
-## Requirements
-
-- WordPress plugin context (`ABSPATH` must be defined).
-- Composer dependency: `yahnis-elsts/plugin-update-checker` (v5+).
-- A public GitHub repository with releases or branch updates.
-
-Install dependency:
+## Installation
 
 ```bash
-composer require yahnis-elsts/plugin-update-checker
+composer require soderlind/wordpress-github-updater
 ```
 
-## Quick Start (Canonical API)
+This automatically includes `yahnis-elsts/plugin-update-checker` as a dependency.
 
-Copy `class-github-plugin-updater.php` into your plugin and initialize like this:
+## Requirements
 
-```php
-if ( ! class_exists( \Soderlind\WordPress\GitHubUpdater::class ) ) {
-	require_once __DIR__ . '/class-github-plugin-updater.php';
-}
+- PHP 7.4+
+- WordPress plugin context (`ABSPATH` must be defined).
+- A GitHub repository with releases or branch updates.
 
-\Soderlind\WordPress\GitHubUpdater::init(
-	github_url: 'https://github.com/username/plugin-name',
-	plugin_file: __FILE__,
-	plugin_slug: 'plugin-name',
-	name_regex: '/plugin-name\.zip/',
-	branch: 'main',
+## Quick Start
+
+```php
+use Soderlind\WordPress\GitHubUpdater;
+
+GitHubUpdater::init(
+	github_url:   'https://github.com/username/plugin-name',
+	plugin_file:  __FILE__,
+	plugin_slug:  'plugin-name',
+	name_regex:   '/plugin-name\.zip/',
+	branch:       'main',
+	check_period: 6,            // Hours between checks (default: 6)
+	auth_token:   '',           // Optional GitHub token
 );
 ```
 
@@ -48,7 +50,20 @@ Positional equivalent:
 	__FILE__,
 	'plugin-name',
 	'/plugin-name\.zip/',
-	'main'
+	'main',
+	6,   // check_period
+	''   // auth_token
+);
+```
+
+### With GitHub Token (for private repos or higher rate limits)
+
+```php
+GitHubUpdater::init(
+	github_url:   'https://github.com/username/private-plugin',
+	plugin_file:  __FILE__,
+	plugin_slug:  'private-plugin',
+	auth_token:   defined('MY_PLUGIN_GITHUB_TOKEN') ? MY_PLUGIN_GITHUB_TOKEN : '',
 );
 ```
 
@@ -61,15 +76,19 @@ Positional equivalent:
 	'https://github.com/username/plugin-name',
 	__FILE__,
 	'plugin-name',
-	'main'
+	'main',
+	6,  // check_period
+	''  // auth_token
 );
 
 \Soderlind\WordPress\GitHub_Plugin_Updater::create_with_assets(
 	'https://github.com/username/plugin-name',
 	__FILE__,
 	'plugin-name',
 	'/plugin-name\.zip/',
-	'main'
+	'main',
+	6,  // check_period
+	''  // auth_token
 );
 ```
 
@@ -84,43 +103,49 @@ Positional equivalent:
 | `plugin_slug` | Yes | - | Plugin slug used by WordPress |
 | `name_regex` | No | `''` | Regex to match release asset zip filename |
 | `branch` | No | `'main'` | Branch to track |
+| `check_period` | No | `6` | Hours between update checks. Set to `0` to disable automatic checks. |
+| `auth_token` | No | `''` | GitHub personal access token for private repos or higher rate limits |
+
+### Rate-Limit Mitigation
 
-Notes:
+This library includes built-in protection against GitHub API timeouts/overload:
 
-- When `name_regex` is empty, release-asset filtering is disabled.
-- `init` registration is deferred to WordPress `init` to be safe regardless of load timing.
+1. **Configurable check interval**: Default is 6 hours (vs. upstream default of 12h). Adjust via `check_period`.
+2. **Throttled checks**: When an update is already known, checks are reduced to every 72 hours.
+3. **Token authentication**: Provide a GitHub token to increase rate limits from 60 to 5000 requests/hour.
+4. **Error logging**: API errors are logged when `WP_DEBUG` is enabled.
 
 ## Recommended Integration Pattern
 
-From your main plugin file, mirror the vmfa pattern:
+From your main plugin file:
 
 ```php
-if ( ! class_exists( \Soderlind\WordPress\GitHubUpdater::class ) ) {
-	require_once __DIR__ . '/class-github-plugin-updater.php';
-}
-
-\Soderlind\WordPress\GitHubUpdater::init(
-	github_url: 'https://github.com/owner/repo',
-	plugin_file: MY_PLUGIN_FILE,
-	plugin_slug: 'my-plugin',
-	name_regex: '/my-plugin\.zip/',
-	branch: 'main',
+// Autoloaded via Composer
+use Soderlind\WordPress\GitHubUpdater;
+
+GitHubUpdater::init(
+	github_url:   'https://github.com/owner/repo',
+	plugin_file:  __FILE__,
+	plugin_slug:  'my-plugin',
+	name_regex:   '/my-plugin\.zip/',
+	branch:       'main',
+	check_period: 6,
 );
 ```
 
-## Workflow Setup
+## Workflow Templates
 
-This repository includes two workflow templates:
+This repository includes two workflow templates in `.github/workflows/`:
 
-- `on-release-add.zip.yml` (release-triggered build + upload)
-- `manually-build-zip.yml` (manual build/upload for a provided tag)
+- `on-release-add.zip.yml` — Release-triggered build + upload
+- `manually-build-zip.yml` — Manual build/upload for a provided tag
 
 Copy them into your plugin repository at `.github/workflows/`.
 
 ### Workflow Checklist
 
 1. Set `PLUGIN_ZIP` to your plugin zip file (example: `my-plugin.zip`).
-2. Keep `composer install --no-dev --optimize-autoloader` so the updater dependency is packaged.
+2. Keep `composer install --no-dev --optimize-autoloader` so dependencies are packaged.
 3. Keep the verification step that checks `vendor/yahnis-elsts/plugin-update-checker` exists in the zip.
 4. Ensure `name_regex` in PHP matches your zip filename convention.
 
@@ -140,11 +165,26 @@ If `plugin-update-checker` is not in `vendor/`, updater setup fails. In `WP_DEBU
 
 ### GitHub API rate limits
 
-Unauthenticated GitHub requests are rate-limited. Keep failed lookup caching enabled in your updater flow and avoid frequent forced checks in production.
+The library includes built-in rate-limit mitigation:
+
+- **Check interval**: By default, checks only every 6 hours.
+- **Throttling**: When an update is already available, checks reduce to every 72 hours.
+- **Token auth**: Pass a GitHub token via `auth_token` to increase limits from 60 to 5000 requests/hour.
+
+If you still hit rate limits, increase `check_period` or add a GitHub token.
 
 ### Private repositories
 
-This wrapper is designed for public GitHub releases. For private repositories, instantiate plugin-update-checker directly and configure authentication with that library.
+Pass your GitHub personal access token via the `auth_token` parameter:
+
+```php
+GitHubUpdater::init(
+	github_url:  'https://github.com/username/private-repo',
+	plugin_file: __FILE__,
+	plugin_slug: 'private-plugin',
+	auth_token:  MY_GITHUB_TOKEN,
+);
+```
 
 ## Real-World Reference