Sdk Laravel Package

## Getting Started

### Minimal Setup
1. **Install the package**:
   ```bash
   composer require astroway/sdk guzzlehttp/guzzle nyholm/psr7

(Guzzle and PSR7 are required for HTTP client functionality if not already present.)

2. Initialize the SDK with your API key (obtained from AstroWay Dashboard):

   use Astroway\Astroway;
   
   $astroway = new Astroway([
       'apiKey' => getenv('ASTROWAY_API_KEY'),
   ]);
   

3. First Use Case: Compute a Natal Chart

   $chart = $astroway->chart()->compute([
       'date' => '1990-07-14',
       'time' => '14:30:00',
       'timezoneOffset' => 3,
       'latitude' => 50.45,
       'longitude' => 30.52,
       'houseSystem' => 'P',
   ]);
   echo "Ascendant: {$chart['angles']['asc']['sign']} {$chart['angles']['asc']['degree']}°";
   

Key Starting Points

• Service Namespaces: Explore the 103 typed service namespaces (e.g., $astroway->synastry(), $astroway->vedic(), $astroway->tarot()).
• Raw API Access: Use $astroway->request() for endpoints not yet covered by services.
• Error Handling: Catch typed exceptions like RateLimitError or AuthenticationError (see Error Handling).

Implementation Patterns

1. Service-Based Workflows

Leverage the 103 typed service namespaces for structured access to AstroWay’s 700+ endpoints. Each service follows a consistent pattern:

$result = $astroway->serviceName()->methodName([
    'param1' => 'value1',
    'param2' => 'value2',
]);

Examples:

• Synastry Compatibility:

  $compatibility = $astroway->synastry()->compute([
      'chart1' => ['date' => '1990-07-14', 'time' => '14:30:00', ...],
      'chart2' => ['date' => '1992-03-22', 'time' => '09:15:00', ...],
  ]);
  echo "Score: {$compatibility['compatibility']['score']}";
  

• Vedic Dashas:

  $dasha = $astroway->vedic()->dashasVimshottariMaha([
      'date' => '1985-07-22',
      'time' => '06:45:00',
      'latitude' => 19.07,
      'longitude' => 72.87,
  ]);
  

2. Batch Processing with Concurrency

Use $astroway->concurrent() to parallelize API calls (e.g., generating multiple charts or synastry reports):

$results = $astroway->concurrent(5)->all([
    fn() => $astroway->chart()->compute($chart1),
    fn() => $astroway->chart()->compute($chart2),
    // ... up to 5 concurrent requests
]);

3. Caching Responses

Cache responses using PSR-16 (e.g., Symfony Cache, Predis):

use Symfony\Contracts\Cache\CacheInterface;

$cache = new Symfony\Cache\Adapter\FilesystemAdapter();
$astroway = new Astroway([
    'apiKey' => getenv('ASTROWAY_API_KEY'),
    'cache' => $cache,
    'cacheTtlSeconds' => 3600, // Cache for 1 hour
]);

Note: Cache invalidation is manual (e.g., clear cache when API keys rotate).

4. Custom HTTP Clients

Integrate with existing HTTP clients (e.g., Symfony’s HttpClient, Buzz) via PSR-18:

use Symfony\Contracts\HttpClient\HttpClientInterface;

$httpClient = Symfony\Contracts\HttpClient\HttpClient::create();
$astroway = new Astroway([
    'apiKey' => getenv('ASTROWAY_API_KEY'),
    'httpClient' => $httpClient,
]);

5. Idempotency for POST Requests

Enable idempotency keys for retries (e.g., to avoid duplicate charges):

$astroway = new Astroway([
    'apiKey' => getenv('ASTROWAY_API_KEY'),
    'idempotency' => true, // Auto-generates Idempotency-Key header
]);

6. Type-Safe Requests with DTOs

Use Data Transfer Objects (DTOs) for validated requests:

use Astroway\DTO\Chart\ComputeRequest;

$request = new ComputeRequest(
    date: '1990-07-14',
    time: '14:30:00',
    timezoneOffset: 3,
    latitude: 50.45,
    longitude: 30.52,
);
$chart = $astroway->chart()->compute($request);

7. Testing with Mock Client

Use MockAstroway for unit tests:

use Astroway\Testing\MockAstroway;

$mock = new MockAstroway();
$mock->expect('chart()->compute')->andReturn(['angles' => ['asc' => ['sign' => 'Aries', 'degree' => 1.5]]]);

$chart = $mock->chart()->compute($request);
assertEquals('Aries', $chart['angles']['asc']['sign']);

Gotchas and Tips

1. API Key Management

• Store securely: Use environment variables or a secrets manager (e.g., Laravel’s .env).
• Rotate keys: Catch AuthenticationError to handle key rotation gracefully.
• Quota tracking: Monitor creditsRemaining in responses or via the AstroWay Dashboard.

2. Retry Logic

• Default behavior: Retries on 408, 409, 429, and 5xx with exponential backoff.
• Customize retries:

  $astroway = new Astroway([
      'retry' => [
          'maxRetries' => 3, // Total attempts = 1 + maxRetries
          'baseDelayMs' => 500,
          'retryableStatuses' => [429, 500, 502], // Override defaults
      ],
  ]);
  

• Disable retries:

  'retry' => ['maxRetries' => 0]
  

3. Error Handling

• Catch specific errors first:

  try {
      $result = $astroway->post('/chart', $body);
  } catch (RateLimitError $e) {
      sleep($e->retryAfterSeconds ?? 60);
      retry();
  } catch (AuthenticationError $e) {
      throw new RuntimeException('Invalid API key');
  } catch (ApiError $e) {
      logError($e->getMessage(), $e->status, $e->requestId);
  }
  

• Key error properties:
  • status: HTTP status code.
  • errorCode: AstroWay-specific error code (e.g., invalid_date).
  • requestId: Server-side trace ID for debugging.
  • creditsRemaining: Remaining API credits.

4. Timezone and Location Handling

• Timezone offsets: Use timezoneOffset (e.g., 3 for UTC+3) instead of IANA timezones.
• Latitude/longitude: Ensure precision (e.g., 50.4500 instead of 50.45).
• House systems: Default is P (Placidus). Use K for Koch or W for Whole Sign.

5. Credit Costs

• Pricing awareness: Endpoints cost 5–500 credits (e.g., a natal chart costs ~5 credits; synastry reports cost ~50).
• Monitor usage: Check creditsRemaining in responses or the dashboard.
• Free tier: 10,000 credits/month (no card required).

6. Performance Tips

• Batch requests: Use $astroway->concurrent() for parallel calls (max 5 concurrent by default).
• Cache responses: Reduce API calls for static data (e.g., cached horoscopes).
• Avoid redundant calls: Reuse $astroway instance (services are memoized).

7. Debugging

• **Enable logging