llms.txt

# Astrology API TypeScript SDK

> Type-safe Node.js client for the Astrology API v3.2.10

## Quick Start

```bash
npm install @astro-api/astroapi-typescript
```

```typescript
import { AstrologyClient } from '@astro-api/astroapi-typescript';

const client = new AstrologyClient({
  apiKey: process.env.ASTROLOGY_API_KEY,
  retry: { attempts: 2, delayMs: 250 },
  debug: false,
});

// Get planetary positions
const positions = await client.data.getPositions({
  subject: {
    name: 'Demo User',
    birth_data: {
      year: 1990,
      month: 5,
      day: 11,
      hour: 18,
      minute: 15,
      city: 'London',
      country_code: 'GB',
      timezone: 'Europe/London',
    },
  },
});
```

## Key Concepts

### AstrologyClient
Main entry point. Configure with `apiKey` (required), `retry`, `debug`, `baseUrl`.

### Subject
Birth data object required by most endpoints:
```typescript
interface Subject {
  name?: string;
  birth_data: {
    year: number;      // e.g., 1990
    month: number;     // 1-12
    day: number;       // 1-31
    hour: number;      // 0-23
    minute: number;    // 0-59
    city: string;      // e.g., 'London'
    country_code: string; // ISO 3166-1 alpha-2, e.g., 'GB'
    timezone?: string; // IANA timezone, e.g., 'Europe/London'
  };
}
```

### DateTimeLocation
For transit and global calculations (no birth data needed):
```typescript
interface DateTimeLocation {
  year: number;
  month: number;
  day: number;
  hour: number;
  minute: number;
  city: string;
  country_code: string;
  timezone?: string;
}
```

## Category Clients

All methods follow pattern: `client.<category>.<method>(request, config?)`

### client.data
Astronomical calculations: planetary positions, aspects, house cusps, lunar metrics.

| Method | Description |
|--------|-------------|
| `getPositions(request)` | Planetary positions in signs/degrees |
| `getEnhancedPositions(request)` | Positions with traditional dignities |
| `getGlobalPositions(request)` | Positions for any datetime (no birth) |
| `getAspects(request)` | Angular relationships between planets |
| `getEnhancedAspects(request)` | Aspects with receptions, strength |
| `getHouseCusps(request)` | 12 house boundary positions |
| `getLunarMetrics(request)` | Moon phase, illumination, void-of-course |
| `getEnhancedLunarMetrics(request)` | Lunar dignities, timing windows |
| `getCurrentMoment()` | Current sky positions |

### client.charts
Chart generation: natal, synastry, composite, transit, returns, progressions.

| Method | Description |
|--------|-------------|
| `getNatalChart(request)` | Birth chart with positions, houses, aspects |
| `getSynastryChart(request)` | Compare two charts side-by-side |
| `getCompositeChart(request)` | Merged relationship chart |
| `getTransitChart(request)` | Current transits to natal |
| `getSolarReturnChart(request)` | Yearly birthday chart |
| `getLunarReturnChart(request)` | Monthly Moon return chart |
| `getProgressions(request)` | Secondary progressions |
| `getDirections(request)` | Solar arc directions |
| `getNatalTransits(request)` | Transit events in date range |

### client.analysis
Interpretation reports: natal, synastry, compatibility, specialized analyses.

| Method | Description |
|--------|-------------|
| `getNatalReport(request)` | Full natal interpretation |
| `getSynastryReport(request)` | Relationship compatibility report |
| `getCompatibilityScore(request)` | Numeric compatibility scores |
| `getCareerAnalysis(request)` | Career-focused interpretation |
| `getHealthAnalysis(request)` | Health indicators |
| `getKarmicAnalysis(request)` | Past life/soul lessons |
| `getTransitReport(request)` | Current transit interpretations |
| `getProgressionReport(request)` | Progression interpretations |

### client.horoscope
Daily, weekly, monthly, yearly horoscopes.

| Method | Description |
|--------|-------------|
| `getPersonalDailyHoroscope(request)` | Personalized daily forecast |
| `getSignDailyHoroscope(request)` | Sun sign daily horoscope |
| `getSignWeeklyHoroscope(request)` | Sun sign weekly forecast |
| `getSignMonthlyHoroscope(request)` | Sun sign monthly forecast |
| `getSignYearlyHoroscope(request)` | Sun sign yearly overview |

### client.insights
Specialized insights: relationship, pet, wellness, financial, business.

| Sub-client | Description |
|------------|-------------|
| `insights.relationship` | Love languages, compatibility, timing |
| `insights.pet` | Pet personality, compatibility, training |
| `insights.wellness` | Biorhythms, body mapping, energy |
| `insights.financial` | Market timing, Gann analysis, crypto |
| `insights.business` | Team dynamics, hiring, leadership |

### client.svg
SVG chart image generation.

| Method | Description |
|--------|-------------|
| `getNatalChartSvg(request)` | SVG natal chart image |
| `getSynastryChartSvg(request)` | SVG synastry bi-wheel |
| `getTransitChartSvg(request)` | SVG transit chart |

### Other Categories

| Category | Prefix | Description |
|----------|--------|-------------|
| `glossary` | `/api/v3/glossary` | Reference data: cities, countries, house systems |
| `astrocartography` | `/api/v3/astrocartography` | Location-based astrology maps |
| `chinese` | `/api/v3/chinese` | BaZi, Chinese zodiac, compatibility |
| `eclipses` | `/api/v3/eclipses` | Eclipse events and natal impact |
| `lunar` | `/api/v3/lunar` | Moon phases, void-of-course, calendar |
| `numerology` | `/api/v3/numerology` | Core numbers, life path, compatibility |
| `tarot` | `/api/v3/tarot` | Card draws, spreads, interpretations |
| `traditional` | `/api/v3/traditional` | Classical astrology techniques |
| `fixedStars` | `/api/v3/fixed-stars` | Fixed star positions, conjunctions |
| `enhanced` | `/api/v3/enhanced*` | Traditional analysis with modern UI |

## Configuration Options

```typescript
interface AstrologyClientConfig {
  apiKey?: string;              // Falls back to ASTROLOGY_API_KEY env var
  baseUrl?: string;             // Default: https://api.astrology-api.io
  timeout?: number;             // Request timeout in ms (default: 30000)
  debug?: boolean;              // Enable debug logging
  logger?: (msg: string) => void; // Custom logger
  retry?: {
    attempts?: number;          // Max retry attempts (default: 3)
    delayMs?: number;           // Base delay between retries (default: 1000)
    statusCodes?: number[];     // HTTP codes to retry (default: [429,500,502,503,504])
  };
}
```

## Error Handling

```typescript
import { AstrologyError } from '@astro-api/astroapi-typescript';

try {
  const result = await client.data.getPositions(request);
} catch (error) {
  if (error instanceof AstrologyError) {
    console.error(`API Error ${error.statusCode}: ${error.message}`);
    if (error.isClientError()) { /* 4xx error */ }
    if (error.isServerError()) { /* 5xx error */ }
  }
}
```

## Documentation Links

- [README.md](https://github.com/astro-api/astroapi-typescript/blob/main/README.md): Overview, installation, examples
- [CLAUDE.md](https://github.com/astro-api/astroapi-typescript/blob/main/CLAUDE.md): AI assistant guidance, architecture
- [API Docs](https://api.astrology-api.io/rapidoc): Full OpenAPI specification
- [npm Package](https://www.npmjs.com/package/@astro-api/astroapi-typescript): Published package

## Common Patterns

### Two-person comparison (synastry)
```typescript
const synastry = await client.analysis.getSynastryReport({
  subject1: personA,
  subject2: personB,
});
```

### Transit analysis
```typescript
const transits = await client.charts.getTransitChart({
  natal_subject: birthSubject,
  transit_datetime: {
    year: 2024, month: 5, day: 11,
    hour: 12, minute: 0,
    city: 'New York', country_code: 'US',
  },
});
```

### Solar Return for a year
```typescript
const solarReturn = await client.charts.getSolarReturnChart({
  subject: birthSubject,
  return_year: 2024,
  return_location: { city: 'New York', country_code: 'US' },
});
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `ASTROLOGY_API_KEY` | API key (auto-injected if not in constructor) |
| `ASTROLOGY_API_BASE_URL` | Override base URL |
| `ASTROLOGY_DEBUG` | Set to `true` for debug logging |