astrobaba-astro-engine-sdk/index.d.ts

Official Node.js SDK for AstroBaba Astro Engine - Professional Vedic Astrology API with automatic retry logic and comprehensive error handling

/**
 * Type definitions for @astrobaba/astro-engine-sdk
 * Complete TypeScript definitions for Vedic Astrology API Client
 */

declare module '@astrobaba/astro-engine-sdk' {
  /**
   * Birth data interface
   */
  export interface BirthData {
    /** Person's name */
    name: string;
    /** Birth date in YYYY-MM-DD format */
    date: string;
    /** Birth time in HH:MM:SS format */
    time: string;
    /** Birth latitude */
    latitude: number;
    /** Birth longitude */
    longitude: number;
    /** Timezone (default: 'Asia/Kolkata') */
    timezone?: string;
  }

  /**
   * SDK Configuration
   */
  export interface AstroEngineConfig {
    /** Base URL for the API (default: 'http://localhost:8000/api/v1') */
    baseUrl?: string;
    /** Request timeout in milliseconds (default: 10000) */
    timeout?: number;
    /** Maximum retry attempts (default: 3) */
    maxRetries?: number;
    /** Initial retry delay in milliseconds (default: 1000) */
    retryDelay?: number;
    /** Exponential backoff multiplier (default: 2) */
    backoffFactor?: number;
  }

  /**
   * API Error
   */
  export interface AstroEngineError extends Error {
    /** HTTP status code */
    status?: number | null;
    /** Error code */
    code: string;
    /** Response data */
    data?: any;
    /** Original error */
    originalError: Error;
  }

  /**
   * Planetary Position
   */
  export interface PlanetaryPosition {
    planet: string;
    sign: string;
    degree: number;
    house: number;
    retrograde: boolean;
    nakshatra: string;
    pada: number;
  }

  /**
   * House Information
   */
  export interface HouseInfo {
    house_number: number;
    sign: string;
    degree: number;
    lord: string;
  }

  /**
   * Birth Chart Response
   */
  export interface BirthChartResponse {
    planets: PlanetaryPosition[];
    houses: HouseInfo[];
    ascendant: {
      sign: string;
      degree: number;
    };
  }

  /**
   * Dasha Period
   */
  export interface DashaPeriod {
    planet: string;
    start_date: string;
    end_date: string;
    duration_years: number;
  }

  /**
   * Vimshottari Dasha Response
   */
  export interface VimshottariDashaResponse {
    current_dasha: DashaPeriod;
    maha_dashas: DashaPeriod[];
  }

  /**
   * Panchang Response
   */
  export interface PanchangResponse {
    tithi: string;
    nakshatra: string;
    yoga: string;
    karana: string;
    paksha: string;
    sunrise: string;
    sunset: string;
    moonrise: string;
    moonset: string;
  }

  /**
   * Divisional Chart Response
   */
  export interface DivisionalChartResponse {
    division: string;
    planets: PlanetaryPosition[];
    houses: HouseInfo[];
  }

  /**
   * KP Chart Response
   */
  export interface KPChartResponse {
    cusps: Array<{
      cusp: number;
      sign: string;
      degree: number;
      star_lord: string;
      sub_lord: string;
    }>;
    planets: Array<{
      planet: string;
      sign: string;
      degree: number;
      star_lord: string;
      sub_lord: string;
    }>;
  }

  /**
   * Ashtakoot Matching Response
   */
  export interface AshtakootMatchingResponse {
    total_points: number;
    max_points: number;
    compatibility_percentage: number;
    ashtakoot_matching: {
      varna: { points: number; max_points: number };
      vashya: { points: number; max_points: number };
      tara: { points: number; max_points: number };
      yoni: { points: number; max_points: number };
      graha_maitri: { points: number; max_points: number };
      gana: { points: number; max_points: number };
      bhakoot: { points: number; max_points: number };
      nadi: { points: number; max_points: number };
    };
    dashakoot_matching?: any;
    mangal_dosha: {
      male: {
        present: boolean;
        severity: string;
      };
      female: {
        present: boolean;
        severity: string;
      };
    };
  }

  /**
   * Yogas & Doshas Response
   */
  export interface YogasAndDoshasResponse {
    yogas: Array<{
      name: string;
      type: string;
      description: string;
      strength: number;
    }>;
    doshas: Array<{
      name: string;
      present: boolean;
      severity: string;
      remedies: string[];
    }>;
  }

  /**
   * Horoscope Response (Daily/Weekly/Monthly/Yearly)
   */
  export interface HoroscopeResponse {
    zodiac_sign: string;
    date?: string;
    period?: string;
    prediction: string;
    lucky_number?: number;
    lucky_color?: string;
    lucky_time?: string;
    mood?: string;
    compatibility?: string[];
  }

  /**
   * Complete Kundli Response
   */
  export interface KundliResponse {
    basic_details: {
      name: string;
      date: string;
      time: string;
      place: string;
      timezone: string;
    };
    birth_chart: BirthChartResponse;
    divisional_charts: {
      [key: string]: DivisionalChartResponse;
    };
    dasha: VimshottariDashaResponse;
    panchang: PanchangResponse;
    yogas_doshas: YogasAndDoshasResponse;
  }

  /**
   * Main SDK Client Class
   */
  export class AstroEngineClient {
    /**
     * Initialize the Astro Engine SDK
     * @param config Configuration options
     */
    constructor(config?: AstroEngineConfig);

    // ==================== CHART ENDPOINTS ====================
    
    /**
     * Calculate birth chart with planetary positions and houses
     * @param birthData Birth data
     * @param houseSystem House system (default: 'PLACIDUS')
     * @returns Birth chart data
     */
    birthChart(
      birthData: BirthData,
      houseSystem?: string
    ): Promise<BirthChartResponse>;

    // ==================== DASHA ENDPOINTS ====================
    
    /**
     * Calculate Vimshottari Dasha periods
     * @param birthData Birth data
     * @param years Years to calculate (default: 120)
     * @returns Dasha periods
     */
    vimshottariDasha(
      birthData: BirthData,
      years?: number
    ): Promise<VimshottariDashaResponse>;

    /**
     * Calculate Antardasha (sub-periods) within a Mahadasha
     * @param mahaDashaLord Maha dasha lord planet
     * @param mahaDashaStart Start date (YYYY-MM-DD)
     * @param mahaDashaYears Duration in years
     * @returns Antardasha periods
     */
    antardasha(
      mahaDashaLord: string,
      mahaDashaStart: string,
      mahaDashaYears: number
    ): Promise<any>;

    // ==================== PANCHANG ENDPOINTS ====================
    
    /**
     * Calculate Panchang (Vedic calendar)
     * @param date Date (YYYY-MM-DD)
     * @param latitude Location latitude
     * @param longitude Location longitude
     * @param timezone Timezone (default: 'Asia/Kolkata')
     * @returns Panchang data
     */
    panchang(
      date: string,
      latitude: number,
      longitude: number,
      timezone?: string
    ): Promise<PanchangResponse>;

    // ==================== DIVISIONAL CHART ENDPOINTS ====================
    
    /**
     * Calculate specific divisional chart
     * @param birthData Birth data
     * @param division Division (D1, D9, D10, etc.)
     * @returns Divisional chart data
     */
    divisionalChart(
      birthData: BirthData,
      division: string
    ): Promise<DivisionalChartResponse>;

    /**
     * Calculate all major divisional charts
     * @param birthData Birth data
     * @returns All divisional charts
     */
    allDivisionalCharts(
      birthData: BirthData
    ): Promise<{ [key: string]: DivisionalChartResponse }>;

    // ==================== KP SYSTEM ENDPOINTS ====================
    
    /**
     * Calculate KP (Krishnamurti Paddhati) system chart
     * @param birthData Birth data
     * @returns KP chart with cusps and sub-lords
     */
    kpChart(birthData: BirthData): Promise<KPChartResponse>;

    // ==================== MATCHING ENDPOINTS ====================
    
    /**
     * Calculate Ashtakoot (8-Kuta) compatibility matching
     * @param maleData Male birth data
     * @param femaleData Female birth data
     * @returns Matching analysis with 8 Kutas
     */
    ashtakootMatching(
      maleData: BirthData,
      femaleData: BirthData
    ): Promise<AshtakootMatchingResponse>;

    // ==================== YOGAS & DOSHAS ENDPOINTS ====================
    
    /**
     * Analyze all yogas and doshas in birth chart
     * @param birthData Birth data
     * @returns Yogas and doshas analysis
     */
    yogasAndDoshas(birthData: BirthData): Promise<YogasAndDoshasResponse>;

    // ==================== HOROSCOPE ENDPOINTS ====================
    
    /**
     * Calculate Ashtakavarga (8-point benefic system)
     * @param birthData Birth data
     * @returns Ashtakavarga analysis
     */
    ashtakavarga(birthData: BirthData): Promise<any>;

    /**
     * Generate comprehensive horoscope report
     * @param birthData Birth data
     * @returns Complete horoscope
     */
    completeHoroscope(birthData: BirthData): Promise<any>;

    // ==================== DAILY HOROSCOPE ENDPOINTS ====================
    
    /**
     * Get daily horoscope for zodiac sign
     * @param zodiacSign Zodiac sign (Aries, Taurus, etc.)
     * @param date Date (YYYY-MM-DD), default: today
     * @returns Daily horoscope
     */
    dailyHoroscope(
      zodiacSign: string,
      date?: string
    ): Promise<HoroscopeResponse>;

    /**
     * Get weekly horoscope for zodiac sign
     * @param zodiacSign Zodiac sign
     * @param startDate Week start date (YYYY-MM-DD)
     * @returns Weekly horoscope
     */
    weeklyHoroscope(
      zodiacSign: string,
      startDate?: string
    ): Promise<HoroscopeResponse>;

    /**
     * Get monthly horoscope for zodiac sign
     * @param zodiacSign Zodiac sign
     * @param year Year
     * @param month Month (1-12)
     * @returns Monthly horoscope
     */
    monthlyHoroscope(
      zodiacSign: string,
      year?: number,
      month?: number
    ): Promise<HoroscopeResponse>;

    /**
     * Get yearly horoscope for zodiac sign
     * @param zodiacSign Zodiac sign
     * @param year Year
     * @returns Yearly horoscope
     */
    yearlyHoroscope(
      zodiacSign: string,
      year?: number
    ): Promise<HoroscopeResponse>;

    /**
     * Get daily horoscope for all zodiac signs
     * @param date Date (YYYY-MM-DD)
     * @returns All signs daily horoscope
     */
    allSignsDailyHoroscope(date?: string): Promise<any>;

    // ==================== KUNDLI ENDPOINTS ====================
    
    /**
     * Generate complete Kundli with all details
     * @param birthData Birth data
     * @returns Complete Kundli analysis
     */
    kundli(birthData: BirthData): Promise<KundliResponse>;

    /**
     * Get basic Kundli information
     * @param birthData Birth data
     * @returns Basic Kundli details
     */
    basicKundli(birthData: BirthData): Promise<any>;

    /**
     * Get planetary positions
     * @param birthData Birth data
     * @returns Planetary positions
     */
    planetaryPositions(birthData: BirthData): Promise<any>;

    /**
     * Get house positions and cusps
     * @param birthData Birth data
     * @returns House details
     */
    housePositions(birthData: BirthData): Promise<any>;

    // ==================== KUNDLI MATCHING ENDPOINTS ====================
    
    /**
     * Comprehensive Kundli matching analysis
     * @param maleData Male birth data
     * @param femaleData Female birth data
     * @returns Detailed matching report
     */
    kundliMatching(
      maleData: BirthData,
      femaleData: BirthData
    ): Promise<any>;

    /**
     * Quick compatibility check
     * @param maleData Male birth data
     * @param femaleData Female birth data
     * @returns Quick compatibility score
     */
    quickCompatibility(
      maleData: BirthData,
      femaleData: BirthData
    ): Promise<any>;

    // ==================== UTILITY METHODS ====================
    
    /**
     * Update configuration
     * @param newConfig New configuration options
     */
    updateConfig(newConfig: Partial<AstroEngineConfig>): void;
  }

  export default AstroEngineClient;
}