docs: add human design and forecast examples, fix endpoint count to 148

Author: ph33nx

AGENTS.md

@@ -52,7 +52,7 @@ $result = $roxy->location->searchCities(q: 'Mumbai');
 | `$roxy->languages` | 1 | List the response languages accepted by the `lang` query parameter on every i18n-aware endpoint |
 <!-- END:DOMAINS -->
 
-131 endpoints across 10 product domains plus usage and languages. Counts auto-sync from `specs/openapi.json` at release time.
+148 endpoints across 12 product domains plus usage and languages. Counts auto-sync from `specs/openapi.json` at release time.
 
 ## Critical patterns
 

README.md

@@ -9,7 +9,7 @@
 [![Packagist](https://img.shields.io/packagist/v/roxyapi/sdk.svg)](https://packagist.org/packages/roxyapi/sdk)
 [![PHP Version](https://img.shields.io/packagist/php-v/roxyapi/sdk.svg)](https://packagist.org/packages/roxyapi/sdk)
 
-Official PHP SDK for [RoxyAPI](https://roxyapi.com): Western and Vedic astrology, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers, location geocoding, and more. 131 endpoints across 12 domains, one API key, one dependency (Saloon).
+Official PHP SDK for [RoxyAPI](https://roxyapi.com): Western and Vedic astrology, Human Design, forecast timelines, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers, location geocoding, and more. 148 endpoints across 12 domains, one API key, one dependency (Saloon).
 
 ## Install
 
@@ -131,6 +131,8 @@ $result = $roxy->astrology->getDailyHoroscope(sign: 'aries');
 
 - `examples/vanilla-php.php` - raw PHP, prints a horoscope
 - `examples/laravel.php` - Laravel service provider snippet
+- `examples/human-design.php` - full Human Design bodygraph, prints type, strategy, and profile
+- `examples/forecast.php` - cross-domain forecast timeline, prints the event count and a sample event
 - `examples/render-with-ui.html` - server-side fetch + browser render via `@roxyapi/ui`
 
 ## Documentation

examples/forecast.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Cross-domain forecast timeline example.
+ *
+ *   ROXY_API_KEY=your-key php examples/forecast.php
+ */
+
+require __DIR__ . '/../vendor/autoload.php';
+
+use RoxyAPI\Sdk\RoxyApiException;
+
+use function RoxyAPI\Sdk\createRoxy;
+
+$apiKey = getenv('ROXY_API_KEY') ?: '';
+if ('' === $apiKey) {
+    fwrite(STDERR, "Set ROXY_API_KEY before running this example.\n");
+    exit(1);
+}
+
+$roxy = createRoxy($apiKey);
+
+try {
+    // birthData is one object, never an array of subjects. timezone is decimal hours or an IANA name.
+    $timeline = $roxy->forecast->generateTimeline(
+        birthData: [
+            'date' => '1990-07-04',
+            'time' => '10:12:00',
+            'timezone' => 5.5,
+            'latitude' => 28.6139,
+            'longitude' => 77.209,
+        ],
+        startDate: '2026-06-01',
+        endDate: '2026-06-30',
+    );
+
+    echo "=== Forecast timeline (2026-06-01 to 2026-06-30) ===\n";
+    echo 'Events: ' . ($timeline['count'] ?? 0) . "\n";
+
+    $first = $timeline['events'][0] ?? null;
+    if (null !== $first) {
+        echo 'First:  [' . ($first['date'] ?? '?') . '] ' . ($first['description'] ?? '?') . "\n";
+        echo 'Domain: ' . ($first['domain'] ?? '?') . ', significance ' . ($first['significance'] ?? '?') . "\n";
+    }
+} catch (RoxyApiException $e) {
+    fwrite(STDERR, "[{$e->statusCode}] {$e->errorCode}: {$e->error}\n");
+    exit(3);
+}

examples/human-design.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Human Design bodygraph example.
+ *
+ *   ROXY_API_KEY=your-key php examples/human-design.php
+ */
+
+require __DIR__ . '/../vendor/autoload.php';
+
+use RoxyAPI\Sdk\RoxyApiException;
+
+use function RoxyAPI\Sdk\createRoxy;
+
+$apiKey = getenv('ROXY_API_KEY') ?: '';
+if ('' === $apiKey) {
+    fwrite(STDERR, "Set ROXY_API_KEY before running this example.\n");
+    exit(1);
+}
+
+$roxy = createRoxy($apiKey);
+
+try {
+    // Full bodygraph in one call. timezone is decimal hours (5.5 = IST) or an IANA name.
+    $chart = $roxy->humanDesign->generateBodygraph(
+        date: '1990-07-04',
+        time: '10:12:00',
+        timezone: 5.5,
+        latitude: 28.6139,
+        longitude: 77.209,
+    );
+
+    echo "=== Human Design bodygraph (1990-07-04 10:12 IST) ===\n";
+    echo 'Type:       ' . ($chart['type'] ?? '?') . "\n";
+    echo 'Strategy:   ' . ($chart['strategy'] ?? '?') . "\n";
+    echo 'Profile:    ' . ($chart['profile'] ?? '?') . "\n";
+    echo 'Definition: ' . ($chart['definition'] ?? '?') . "\n";
+} catch (RoxyApiException $e) {
+    fwrite(STDERR, "[{$e->statusCode}] {$e->errorCode}: {$e->error}\n");
+    exit(3);
+}