Added features of CircuitBreaker, Retry, Logger, and documentation

Author: Surfoo

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php-version: [ '8.1', '8.2', '8.3', '8.4']
+        php-version: [ '8.2', '8.3', '8.4']
     steps:
       - uses: "actions/checkout@v4"
       - uses: "shivammathur/setup-php@v2"
@@ -51,7 +51,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php-version: [ '8.1', '8.2', '8.3', '8.4' ]
+        php-version: [ '8.2', '8.3', '8.4' ]
     steps:
       - uses: "actions/checkout@v4"
       - uses: "shivammathur/setup-php@v2"

CHANGELOG.md

@@ -4,6 +4,16 @@ 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).
 
+## [4.0.0] - 2025-12
+### Added
+    - Full HTTP observability tools: structured logging with token masking, per-status log levels, and custom logger support.
+    - Reliability features: retry strategies (exponential and fixed), circuit breaker, and a combined reliability plugin.
+    - Automatic token refresh helpers (with provider auto-creation) and documented token storage guidance.
+    - New documentation set under `docs/` with getting started, authentication, configuration, reliability, and domain-by-domain usage examples.
+
+### Changed
+    - Raised minimum supported PHP version to 8.2.
+
 ## [3.20.0] - 2023-04-27
 ### Added
     - isReferenceCode() and isGeocode() methods
@@ -56,4 +66,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [3.11.0] - 2020-05-22
 ### Added
-    - http options [from Guzzle](http://docs.guzzlephp.org/en/stable/request-options.html) added to all methods if needed (last argument)
+    - http options [from Guzzle](http://docs.guzzlephp.org/en/stable/request-options.html) added to all methods if needed (last argument)

CLAUDE.md

@@ -1,4 +1,4 @@
-PHP project (>=8.1) with Symfony.
+PHP project (>=8.2) with Symfony.
 
 This project is a PHP library for using the Geocaching API.
 - Official API Swagger: https://api.groundspeak.com/api-docs/v1/swagger

README.md

@@ -15,7 +15,7 @@ You can follow changes about the documentation and the API here:
 
 ## Requirements
 
-- PHP >= 8.1
+- PHP >= 8.2
 - [composer](https://getcomposer.org/doc/00-intro.md#system-requirements).
 
 ## Composer
@@ -32,13 +32,9 @@ First, you must have your API key from Groundspeak, but access to the API are no
 
 You can find an example of implementation (with OAuth 2) in this repository: https://github.com/Surfoo/geocaching-api-demo
 
-## Usage Guide
+## Documentation
 
-See [`USAGE.md`](./USAGE.md) for detailed usage instructions, including:
-
-- Basic usage examples
-- Complete API method reference
-- HTTP logging configuration
+Start with [`docs/README.md`](./docs/README.md) for getting started, authentication, configuration, reliability patterns, and domain-by-domain API examples.
 
 ## HTTP Request/Response Logging
 

USAGE.md

@@ -22,7 +22,7 @@
         }
     },
     "require": {
-        "php": "^8.1",
+        "php": "^8.2",
         "monolog/monolog": "^3.0",
         "nyholm/psr7": "^1.8",
         "php-http/client-common": "^2.7",

composer.json

@@ -0,0 +1,10 @@
+# Geocaching PHP SDK Documentation
+
+This folder collects the SDK documentation with examples for the Groundspeak Geocaching API. Each page focuses on a specific topic so you can jump straight to what you need.
+
+## Contents
+- [Getting Started](./getting-started.md) — install the package, create an SDK client, and make your first request.
+- [Authentication & Tokens](./authentication.md) — work with access tokens, wire OAuth, and enable automatic refresh.
+- [Configuration & HTTP Clients](./configuration.md) — understand runtime options, environments, and how to plug in custom PSR clients.
+- [Reliability & Observability](./reliability.md) — enable structured logging, retries, and circuit breaking for resilient calls.
+- [API Usage by Domain](./api-usage.md) — call the main API areas (geocaches, users, adventures, trackables, lists, status) with documented examples.