Update CLAUDE.md and README.md with enhanced project documentation and command details; remove obsolete openapi.json file.

Author: serslon

.cursorrules

@@ -0,0 +1,90 @@
+You are working on `procoders/astrology-api-php` — a PHP 8.1+ SDK for the Astrology API v3.
+
+# Stack
+- PHP 8.1+ with `declare(strict_types=1)` in every file
+- Guzzle 7 for HTTP
+- PHPUnit 10 for testing
+- PHP-CS-Fixer (PSR-12 + single quotes + short arrays + strict params)
+
+# Architecture
+Entry point: `src/AstrologyClient.php` — creates Guzzle client with middleware (retry, API key, logging) and 26 readonly category client properties.
+
+Data flow: CategoryClient method → Validators::validate*() → $this->http->post() → GuzzleHttpHelper → Guzzle → API
+
+Key files:
+- `src/Categories/BaseCategoryClient.php` — abstract base with `buildUrl(string ...$segments)`
+- `src/Utils/HttpHelper.php` — interface: get/post/put/delete
+- `src/Utils/GuzzleHttpHelper.php` — extracts `data` or `result` from JSON responses
+- `src/Utils/Validators.php` — all static validation, throws `AstrologyError`
+- `src/Exceptions/AstrologyError.php` — single exception type with statusCode, errorCode, details
+- `src/Categories/InsightsClient.php` — special: contains 5 nested sub-clients
+
+# Strict Rules
+1. Every class is `final` unless it needs inheritance
+2. Use `readonly` properties for immutable state
+3. Category client methods return `mixed`, take `array $options = []` as last param
+4. Validate BEFORE HTTP calls, never after
+5. Only throw `AstrologyError` — never other exception types
+6. Validation context strings: `'ClassName.fieldName'` format
+7. `buildUrl()` accepts only strings — cast integers: `(string) $year`
+
+# New Category Client Pattern
+```php
+<?php
+declare(strict_types=1);
+namespace Procoders\AstrologyApi\Categories;
+use Procoders\AstrologyApi\Utils\HttpHelper;
+use Procoders\AstrologyApi\Utils\Validators;
+
+final class FooClient extends BaseCategoryClient
+{
+    private const API_PREFIX = '/api/v3/foo';
+    public function __construct(HttpHelper $http) { parent::__construct($http, self::API_PREFIX); }
+
+    public function getBar(array $request, array $options = []): mixed
+    {
+        Validators::validateSubject($request['subject'] ?? [], 'BarRequest.subject');
+        return $this->http->post($this->buildUrl('bar'), $request, $options);
+    }
+}
+```
+Then register in AstrologyClient.php: add use import, readonly property, constructor instantiation.
+
+# Unit Test Pattern
+Use `SpyHttpHelper` (captures lastMethod, lastPath, lastPayload, lastQuery, lastOptions):
+```php
+$this->http = new SpyHttpHelper();
+$this->client = new FooClient($this->http);
+$this->client->getBar(['subject' => $this->subject()]);
+self::assertSame('/api/v3/foo/bar', $this->http->lastPath);
+```
+
+# Integration Test Pattern
+Extend `IntegrationTestCase` — auto-skips without `ASTROLOGY_API_KEY` env var:
+```php
+$response = self::$client->foo->getBar(['subject' => $this->subject()]);
+$this->assertSuccessResponse($response);
+```
+Real API needs location inside `birth_data`: latitude, longitude, city, nation, timezone.
+
+# Validation Reference
+Subject: birth_data with year(1900-2100), month(1-12), day(1-31), hour(0-23), minute(0-59), second(0-59)
+Sun signs: Aries..Pisces + Ari,Tau,Gem,Can,Vir,Lib,Sco,Sag,Cap,Aqu,Pis
+Horoscope formats: paragraph, bullets, short, long
+Progression types: secondary, primary, tertiary, minor
+Direction types: solar_arc, symbolic, profection, naibod
+House systems: P, W, K, A, R, C, B, M, O, E, V, X, H, T, G
+
+# Commands
+```
+composer test           # all tests
+composer test:unit      # mocked unit tests
+composer test:integration  # real API (needs ASTROLOGY_API_KEY)
+composer lint           # check style
+composer lint:fix       # auto-fix
+```
+
+# Pitfalls
+- SVG/PDF endpoints return non-JSON — don't assume array
+- InsightsClient has nested sub-clients: $client->insights->relationship->getCompatibility(...)
+- Use caret constraints (^7.5) not exact versions — this is a library

.github/copilot-instructions.md

@@ -0,0 +1,66 @@
+# Copilot Instructions for procoders/astrology-api-php
+
+PHP 8.1+ SDK for the Astrology API v3. Guzzle 7 HTTP transport. Standalone library (no framework).
+
+## Code Style
+
+- `declare(strict_types=1)` in every file
+- PSR-12 with single quotes, short array syntax `[]`, strict params
+- All classes `final` unless they need inheritance
+- PHP 8.1+ `readonly` properties for immutable state
+- Namespace: `Procoders\AstrologyApi\` maps to `src/`
+
+## Architecture
+
+`AstrologyClient` is the entry point with 26 readonly category client properties (e.g. `$client->charts`, `$client->horoscope`). Each category client extends `BaseCategoryClient` which provides `buildUrl(string ...$segments)` for URL construction.
+
+Data flow: validate inputs via `Validators::validate*()` → call `$this->http->post/get()` → `GuzzleHttpHelper` normalizes response (extracts `data` or `result` key from JSON).
+
+Only exception type: `AstrologyError` (statusCode, errorCode, details, isClientError(), isServerError()).
+
+## Category Client Method Pattern
+
+```php
+public function getBar(array $request, array $options = []): mixed
+{
+    Validators::validateSubject($request['subject'] ?? [], 'BarRequest.subject');
+    return $this->http->post($this->buildUrl('bar'), $request, $options);
+}
+```
+
+Rules:
+- Return type is always `mixed`
+- `$options` is always the last parameter
+- Validate BEFORE HTTP call
+- Validation context: `'ClassName.fieldName'`
+- `buildUrl()` takes only strings — cast integers: `(string) $year`
+
+## Test Pattern (Unit)
+
+Use `SpyHttpHelper` — captures lastMethod, lastPath, lastPayload, lastQuery:
+```php
+$this->http = new SpyHttpHelper();
+$this->client = new FooClient($this->http);
+$this->client->getBar(['subject' => $this->subject()]);
+self::assertSame('/api/v3/foo/bar', $this->http->lastPath);
+```
+
+## Test Pattern (Integration)
+
+Extend `IntegrationTestCase` (auto-skips without `ASTROLOGY_API_KEY`):
+```php
+$response = self::$client->foo->getBar(['subject' => $this->subject()]);
+$this->assertSuccessResponse($response);
+```
+
+## Validation Reference
+
+Subject birth_data requires: year (1900-2100), month (1-12), day (1-31), hour (0-23), minute (0-59), second (0-59). Optional: latitude, longitude, city, country_code.
+
+Enums: Sun signs (Aries..Pisces + 3-letter), horoscope formats (paragraph/bullets/short/long), progression types (secondary/primary/tertiary/minor), direction types (solar_arc/symbolic/profection/naibod), house systems (P/W/K/A/R/C/B/M/O/E/V/X/H/T/G).
+
+## Important Notes
+
+- `InsightsClient` has nested sub-clients: `$client->insights->relationship->getCompatibility(...)`
+- SVG/PDF endpoints return non-JSON (raw strings) — don't assume array response
+- Real API requires location data INSIDE `birth_data` (latitude, longitude, city, nation, timezone)