divineapi 1.1.0__tar.gz → 1.3.0__tar.gz

{divineapi-1.1.0 → divineapi-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: divineapi
-Version: 1.1.0
+Version: 1.3.0
 Summary: Official Python SDK for the Divine API - Astrology, Numerology, Tarot & more
 Author-email: Divine API <support@divineapi.com>
 License: MIT
@@ -51,9 +51,9 @@ from divineapi import DivineApi
 
 client = DivineApi(api_key="your-api-key", auth_token="your-bearer-token")
 
-# Daily Horoscope
+# Daily Horoscope (h_day = today, tomorrow, or yesterday)
 result = client.horoscope.daily(
-    sign="aries", day=10, month=3, year=2024, tzone=5.5
+    sign="aries", h_day="today", tzone=5.5
 )
 print(result)
 ```
@@ -64,10 +64,11 @@ print(result)
 
 ```python
 # Daily / Weekly / Monthly / Yearly Horoscope
-client.horoscope.daily(sign="aries", day=10, month=3, year=2024, tzone=5.5)
-client.horoscope.weekly(sign="leo", week="thisweek", tzone=5.5)
-client.horoscope.monthly(sign="cancer", month=3, tzone=5.5)
-client.horoscope.yearly(sign="virgo", year=2024, tzone=5.5)
+# daily h_day = today / tomorrow / yesterday; weekly/monthly/yearly = current / prev / next
+client.horoscope.daily(sign="aries", h_day="today", tzone=5.5)
+client.horoscope.weekly(sign="leo", week="current", tzone=5.5)
+client.horoscope.monthly(sign="cancer", month="current", tzone=5.5)
+client.horoscope.yearly(sign="virgo", year="current", tzone=5.5)
 
 # Chinese & Numerology Horoscope
 client.horoscope.chinese(sign="rat", h_day="today", tzone=5.5)
@@ -164,8 +165,9 @@ client.indian.festival.chaitra_festivals(
 client.indian.festival.english_calendar(
     year=2024, month=3, place="Delhi", lat=28.6, lon=77.2, tzone=5.5
 )
+# festival is a lowercase snake_case slug from the Divine festival list
 client.indian.festival.find_festival(
-    festival="diwali", year=2024,
+    festival="maha_shivratri", year=2024,
     place="Delhi", lat=28.6, lon=77.2, tzone=5.5
 )
 client.indian.festival.malayalam_festivals(
@@ -174,6 +176,9 @@ client.indian.festival.malayalam_festivals(
 client.indian.festival.tamil_festivals(
     year=2027, place="Chennai", lat=13.0827, lon=80.2707, tzone=5.5
 )
+client.indian.festival.sankranti_festivals(
+    year=2027, place="New Delhi", lat=28.6139, lon=77.2090, tzone=5.5
+)
 ```
 
 ### Western Astrology - Natal
@@ -190,7 +195,7 @@ client.western.natal.house_cusps(**birth_w)
 client.western.natal.aspect_table(**birth_w)
 client.western.natal.natal_wheel_chart(**birth_w)
 client.western.natal.natal_insights(**birth_w)
-client.western.natal.dominants(method="traditional", **birth_w)
+client.western.natal.dominants(method="TRADITIONAL", **birth_w)
 ```
 
 ### Western Astrology - Synastry
@@ -249,7 +254,7 @@ client.lifestyle.astro_chic_picks(sign="virgo", h_day="today", tzone=5.5)
 ### Calculators
 
 ```python
-client.calculators.flames(full_name="John", partner_name="Jane")
+client.calculators.flames(your_name="John", partner_name="Jane")
 client.calculators.love_calculator(
     your_name="John", partner_name="Jane",
     your_gender="male", partner_gender="female",
@@ -259,11 +264,15 @@ client.calculators.love_calculator(
 ### PDF Reports
 
 ```python
+# The six branding fields (company_url, logo_url, footer_text, company_name,
+# company_email, company_bio) are REQUIRED by the PDF backend.
 client.pdf.kundali_sampoorna(
     full_name="John", day=1, month=1, year=1990,
     hour=10, min=30, sec=0, gender="male",
     place="Mumbai", lat=19.07, lon=72.87, tzone=5.5,
     company_name="AstroCo", company_url="https://example.com",
+    company_email="hello@example.com", company_bio="We do astrology.",
+    logo_url="https://example.com/logo.png", footer_text="(c) AstroCo",
 )
 ```
 
@@ -275,7 +284,7 @@ from divineapi import DivineApi, AuthenticationError, ValidationError, RateLimit
 client = DivineApi(api_key="...", auth_token="...")
 
 try:
-    result = client.horoscope.daily(sign="aries", day=10, month=3, year=2024, tzone=5.5)
+    result = client.horoscope.daily(sign="aries", h_day="today", tzone=5.5)
 except AuthenticationError as e:
     print(f"Auth failed: {e}")
 except ValidationError as e:
@@ -288,7 +297,7 @@ except RateLimitError as e:
 
 ```python
 with DivineApi(api_key="...", auth_token="...") as client:
-    result = client.horoscope.daily(sign="aries", day=10, month=3, year=2024, tzone=5.5)
+    result = client.horoscope.daily(sign="aries", h_day="today", tzone=5.5)
 ```
 
 ## Configuration

{divineapi-1.1.0 → divineapi-1.3.0}/README.md

@@ -23,9 +23,9 @@ from divineapi import DivineApi
 
 client = DivineApi(api_key="your-api-key", auth_token="your-bearer-token")
 
-# Daily Horoscope
+# Daily Horoscope (h_day = today, tomorrow, or yesterday)
 result = client.horoscope.daily(
-    sign="aries", day=10, month=3, year=2024, tzone=5.5
+    sign="aries", h_day="today", tzone=5.5
 )
 print(result)
 ```
@@ -36,10 +36,11 @@ print(result)
 
 ```python
 # Daily / Weekly / Monthly / Yearly Horoscope
-client.horoscope.daily(sign="aries", day=10, month=3, year=2024, tzone=5.5)
-client.horoscope.weekly(sign="leo", week="thisweek", tzone=5.5)
-client.horoscope.monthly(sign="cancer", month=3, tzone=5.5)
-client.horoscope.yearly(sign="virgo", year=2024, tzone=5.5)
+# daily h_day = today / tomorrow / yesterday; weekly/monthly/yearly = current / prev / next
+client.horoscope.daily(sign="aries", h_day="today", tzone=5.5)
+client.horoscope.weekly(sign="leo", week="current", tzone=5.5)
+client.horoscope.monthly(sign="cancer", month="current", tzone=5.5)
+client.horoscope.yearly(sign="virgo", year="current", tzone=5.5)
 
 # Chinese & Numerology Horoscope
 client.horoscope.chinese(sign="rat", h_day="today", tzone=5.5)
@@ -136,8 +137,9 @@ client.indian.festival.chaitra_festivals(
 client.indian.festival.english_calendar(
     year=2024, month=3, place="Delhi", lat=28.6, lon=77.2, tzone=5.5
 )
+# festival is a lowercase snake_case slug from the Divine festival list
 client.indian.festival.find_festival(
-    festival="diwali", year=2024,
+    festival="maha_shivratri", year=2024,
     place="Delhi", lat=28.6, lon=77.2, tzone=5.5
 )
 client.indian.festival.malayalam_festivals(
@@ -146,6 +148,9 @@ client.indian.festival.malayalam_festivals(
 client.indian.festival.tamil_festivals(
     year=2027, place="Chennai", lat=13.0827, lon=80.2707, tzone=5.5
 )
+client.indian.festival.sankranti_festivals(
+    year=2027, place="New Delhi", lat=28.6139, lon=77.2090, tzone=5.5
+)
 ```
 
 ### Western Astrology - Natal
@@ -162,7 +167,7 @@ client.western.natal.house_cusps(**birth_w)
 client.western.natal.aspect_table(**birth_w)
 client.western.natal.natal_wheel_chart(**birth_w)
 client.western.natal.natal_insights(**birth_w)
-client.western.natal.dominants(method="traditional", **birth_w)
+client.western.natal.dominants(method="TRADITIONAL", **birth_w)
 ```
 
 ### Western Astrology - Synastry
@@ -221,7 +226,7 @@ client.lifestyle.astro_chic_picks(sign="virgo", h_day="today", tzone=5.5)
 ### Calculators
 
 ```python
-client.calculators.flames(full_name="John", partner_name="Jane")
+client.calculators.flames(your_name="John", partner_name="Jane")
 client.calculators.love_calculator(
     your_name="John", partner_name="Jane",
     your_gender="male", partner_gender="female",
@@ -231,11 +236,15 @@ client.calculators.love_calculator(
 ### PDF Reports
 
 ```python
+# The six branding fields (company_url, logo_url, footer_text, company_name,
+# company_email, company_bio) are REQUIRED by the PDF backend.
 client.pdf.kundali_sampoorna(
     full_name="John", day=1, month=1, year=1990,
     hour=10, min=30, sec=0, gender="male",
     place="Mumbai", lat=19.07, lon=72.87, tzone=5.5,
     company_name="AstroCo", company_url="https://example.com",
+    company_email="hello@example.com", company_bio="We do astrology.",
+    logo_url="https://example.com/logo.png", footer_text="(c) AstroCo",
 )
 ```
 
@@ -247,7 +256,7 @@ from divineapi import DivineApi, AuthenticationError, ValidationError, RateLimit
 client = DivineApi(api_key="...", auth_token="...")
 
 try:
-    result = client.horoscope.daily(sign="aries", day=10, month=3, year=2024, tzone=5.5)
+    result = client.horoscope.daily(sign="aries", h_day="today", tzone=5.5)
 except AuthenticationError as e:
     print(f"Auth failed: {e}")
 except ValidationError as e:
@@ -260,7 +269,7 @@ except RateLimitError as e:
 
 ```python
 with DivineApi(api_key="...", auth_token="...") as client:
-    result = client.horoscope.daily(sign="aries", day=10, month=3, year=2024, tzone=5.5)
+    result = client.horoscope.daily(sign="aries", h_day="today", tzone=5.5)
 ```
 
 ## Configuration

{divineapi-1.1.0 → divineapi-1.3.0}/divineapi/__init__.py

@@ -5,7 +5,7 @@ Usage::
     from divineapi import DivineApi
 
     client = DivineApi(api_key="your-api-key", auth_token="your-bearer-token")
-    result = client.horoscope.daily(sign="aries", day=10, month=3, year=2024, tzone=5.5)
+    result = client.horoscope.daily(sign="aries", h_day="today", tzone=5.5)
     print(result)
 """
 
@@ -29,7 +29,7 @@ from .numerology import NumerologyApi
 from .pdf import PdfReportApi
 from .western import WesternApi
 
-__version__ = "1.1.0"
+__version__ = "1.3.0"
 
 __all__ = [
     "DivineApi",
@@ -57,7 +57,7 @@ class DivineApi:
         client = DivineApi(api_key="...", auth_token="...")
 
         # Horoscope & Tarot
-        client.horoscope.daily(sign="aries", day=10, month=3, year=2024, tzone=5.5)
+        client.horoscope.daily(sign="aries", h_day="today", tzone=5.5)
 
         # Indian Panchang
         client.indian.panchang.find_panchang(
@@ -100,7 +100,9 @@ class DivineApi:
             full_name="John", day=1, month=1, year=1990,
             hour=10, min=30, sec=0, gender="male",
             place="Mumbai", lat=19.07, lon=72.87, tzone=5.5,
-            company_name="MyCompany",
+            company_name="MyCompany", company_url="https://example.com",
+            company_email="hello@example.com", company_bio="We do astrology.",
+            logo_url="https://example.com/logo.png", footer_text="(c) MyCompany",
         )
     """
 

{divineapi-1.1.0 → divineapi-1.3.0}/divineapi/calculators.py

@@ -13,10 +13,10 @@ class CalculatorApi:
     def __init__(self, client: BaseClient) -> None:
         self._c = client
 
-    def flames(self, full_name: str, partner_name: str) -> Dict[str, Any]:
+    def flames(self, your_name: str, partner_name: str) -> Dict[str, Any]:
         """FLAMES Calculator."""
         return self._c.post(HOST, "/calculator/v1/flames-calculator", {
-            "full_name": full_name, "partner_name": partner_name,
+            "your_name": your_name, "partner_name": partner_name,
         })
 
     def love_calculator(

{divineapi-1.1.0 → divineapi-1.3.0}/divineapi/horoscope.py

@@ -20,16 +20,21 @@ class HoroscopeApi:
     def daily(
         self,
         sign: str,
-        day: int,
-        month: int,
-        year: int,
+        h_day: str,
         tzone: float,
         lan: str = "en",
+        day: Optional[int] = None,
+        month: Optional[int] = None,
+        year: Optional[int] = None,
     ) -> Dict[str, Any]:
-        """Daily Horoscope."""
+        """Daily Horoscope.
+
+        The reading is selected with ``h_day`` ('today', 'tomorrow', or
+        'yesterday'). ``day``/``month``/``year`` are deprecated: the API
+        ignores them and they are accepted only for backward compatibility.
+        """
         return self._c.post(HOST, "/api/v5/daily-horoscope", {
-            "sign": sign, "day": day, "month": month, "year": year,
-            "tzone": tzone, "lan": lan,
+            "sign": sign, "h_day": h_day, "tzone": tzone, "lan": lan,
         })
 
     def weekly(
@@ -39,7 +44,10 @@ class HoroscopeApi:
         tzone: float,
         lan: str = "en",
     ) -> Dict[str, Any]:
-        """Weekly Horoscope."""
+        """Weekly Horoscope.
+
+        ``week`` is a selector: 'current', 'prev', or 'next' (not a date).
+        """
         return self._c.post(HOST, "/api/v5/weekly-horoscope", {
             "sign": sign, "week": week, "tzone": tzone, "lan": lan,
         })
@@ -47,11 +55,15 @@ class HoroscopeApi:
     def monthly(
         self,
         sign: str,
-        month: int,
+        month: str,
         tzone: float,
         lan: str = "en",
     ) -> Dict[str, Any]:
-        """Monthly Horoscope."""
+        """Monthly Horoscope.
+
+        ``month`` is a selector: 'current', 'prev', or 'next' (not a calendar
+        month number).
+        """
         return self._c.post(HOST, "/api/v5/monthly-horoscope", {
             "sign": sign, "month": month, "tzone": tzone, "lan": lan,
         })
@@ -59,11 +71,15 @@ class HoroscopeApi:
     def yearly(
         self,
         sign: str,
-        year: int,
+        year: str,
         tzone: float,
         lan: str = "en",
     ) -> Dict[str, Any]:
-        """Yearly Horoscope."""
+        """Yearly Horoscope.
+
+        ``year`` is a selector: 'current', 'prev', or 'next' (not a calendar
+        year number).
+        """
         return self._c.post(HOST, "/api/v5/yearly-horoscope", {
             "sign": sign, "year": year, "tzone": tzone, "lan": lan,
         })

{divineapi-1.1.0 → divineapi-1.3.0}/divineapi/indian/festival.py

@@ -129,3 +129,11 @@ class FestivalApi:
         """Tamil Festivals for a year."""
         return self._c.post(HOST, "/indian-api/v1/tamil-festivals",
                             self._festival_loc(year, place, lat, lon, tzone))
+
+    def sankranti_festivals(
+        self, year: int,
+        place: str, lat: float, lon: float, tzone: float,
+    ) -> Dict[str, Any]:
+        """Sankranti Festivals for a year."""
+        return self._c.post(HOST, "/indian-api/v1/sankranti-festivals",
+                            self._festival_loc(year, place, lat, lon, tzone))

{divineapi-1.1.0 → divineapi-1.3.0}/divineapi/pdf.py

@@ -22,23 +22,26 @@ class PdfReportApi:
         full_name: str, day: int, month: int, year: int,
         hour: int, min: int, sec: int, gender: str,
         place: str, lat: float, lon: float, tzone: float,
-        lan: str = "en",
-        company_name: str = "", company_url: str = "",
-        company_email: str = "", company_mobile: str = "",
-        company_bio: str = "", logo_url: str = "",
-        footer_text: str = "",
+        company_name: str, company_url: str, company_email: str,
+        company_bio: str, logo_url: str, footer_text: str,
+        lan: str = "en", company_mobile: str = "",
         **extra: Any,
     ) -> Dict[str, Any]:
+        # The six branding fields are REQUIRED by the PDF backend (it rejects
+        # requests without them). company_mobile is optional and sent only when
+        # provided.
         d: Dict[str, Any] = {
             "full_name": full_name, "day": day, "month": month, "year": year,
             "hour": hour, "min": min, "sec": sec, "gender": gender,
             "place": place, "lat": lat, "lon": lon, "tzone": tzone,
             "lan": lan,
             "company_name": company_name, "company_url": company_url,
-            "company_email": company_email, "company_mobile": company_mobile,
+            "company_email": company_email,
             "company_bio": company_bio, "logo_url": logo_url,
             "footer_text": footer_text,
         }
+        if company_mobile:
+            d["company_mobile"] = company_mobile
         d.update(extra)
         return d
 
@@ -50,13 +53,12 @@ class PdfReportApi:
         p2_full_name: str, p2_day: int, p2_month: int, p2_year: int,
         p2_hour: int, p2_min: int, p2_sec: int, p2_gender: str,
         p2_place: str, p2_lat: float, p2_lon: float, p2_tzone: float,
-        lan: str = "en",
-        company_name: str = "", company_url: str = "",
-        company_email: str = "", company_mobile: str = "",
-        company_bio: str = "", logo_url: str = "",
-        footer_text: str = "",
+        company_name: str, company_url: str, company_email: str,
+        company_bio: str, logo_url: str, footer_text: str,
+        lan: str = "en", company_mobile: str = "",
         **extra: Any,
     ) -> Dict[str, Any]:
+        # The six branding fields are REQUIRED by the PDF backend.
         d: Dict[str, Any] = {
             "p1_full_name": p1_full_name, "p1_day": p1_day, "p1_month": p1_month,
             "p1_year": p1_year, "p1_hour": p1_hour, "p1_min": p1_min,
@@ -68,10 +70,12 @@ class PdfReportApi:
             "p2_lat": p2_lat, "p2_lon": p2_lon, "p2_tzone": p2_tzone,
             "lan": lan,
             "company_name": company_name, "company_url": company_url,
-            "company_email": company_email, "company_mobile": company_mobile,
+            "company_email": company_email,
             "company_bio": company_bio, "logo_url": logo_url,
             "footer_text": footer_text,
         }
+        if company_mobile:
+            d["company_mobile"] = company_mobile
         d.update(extra)
         return d
 
@@ -133,11 +137,14 @@ class PdfReportApi:
     # Astrology / Numerology reports with report_code
     # ------------------------------------------------------------------ #
 
-    def natal_report(self, report_code: str, theme: str = "", **kw: Any) -> Dict[str, Any]:
-        """Natal Report PDF."""
+    def natal_report(self, report_code: str, theme: str, **kw: Any) -> Dict[str, Any]:
+        """Natal Report PDF.
+
+        Both ``report_code`` (e.g. 'CAREER-REPORT') and ``theme`` (e.g. '001')
+        are required by the API, along with the six company branding fields.
+        """
         kw["report_code"] = report_code
-        if theme:
-            kw["theme"] = theme
+        kw["theme"] = theme
         return self._post_birth("/astrology/v2/report", **kw)
 
     def natal_couple_report(self, report_code: str, **kw: Any) -> Dict[str, Any]:

divineapi-1.3.0/divineapi/western/_house_system.py

@@ -0,0 +1,52 @@
+"""House-system name resolution for the Western API.
+
+The live Western API accepts ONLY single-letter Swiss Ephemeris house-system
+codes. Word values like ``placidus`` are rejected on astroapi-4 and silently
+ignored on astroapi-8, so every payload must send the letter code. This mirrors
+the mapping used by the Divine Western MCP server.
+"""
+
+from typing import Optional
+
+# Friendly house-system names mapped to the single-letter API codes.
+HOUSE_SYSTEM_MAP = {
+    "placidus": "P",
+    "koch": "K",
+    "porphyry": "O",
+    "regiomontanus": "R",
+    "campanus": "C",
+    "equal": "E",
+    "whole-sign": "W",
+    "whole_sign": "W",
+    "wholesign": "W",
+    "morinus": "M",
+    "alcabitius": "B",
+}
+VALID_HOUSE_SYSTEM_LETTERS = set(HOUSE_SYSTEM_MAP.values())
+HOUSE_SYSTEM_FRIENDLY_NAMES = (
+    "placidus, koch, porphyry, regiomontanus, campanus, equal, "
+    "whole-sign, morinus, alcabitius"
+)
+
+
+def resolve_house_system(value: Optional[str]) -> str:
+    """Map a friendly house-system name to its single-letter API code.
+
+    Accepts friendly names case-insensitively (e.g. ``placidus``, ``Whole-Sign``)
+    and already-valid single letters (passed through unchanged, upper-cased).
+    An empty value defaults to ``P`` (Placidus). Raises ``ValueError`` for
+    anything else.
+    """
+    hs = (value or "").strip()
+    if not hs:
+        return "P"
+    if hs.upper() in VALID_HOUSE_SYSTEM_LETTERS:
+        return hs.upper()
+    mapped = HOUSE_SYSTEM_MAP.get(hs.lower())
+    if mapped:
+        return mapped
+    raise ValueError(
+        f"Invalid house_system '{value}'. Must be one of: "
+        f"{HOUSE_SYSTEM_FRIENDLY_NAMES} (or a single-letter code: "
+        f"{', '.join(sorted(VALID_HOUSE_SYSTEM_LETTERS))})"
+    )

{divineapi-1.1.0 → divineapi-1.3.0}/divineapi/western/composite.py

@@ -3,6 +3,7 @@
 from typing import Any, Dict
 
 from ..client import BaseClient
+from ._house_system import resolve_house_system
 
 HOST = "astroapi-8"
 
@@ -33,7 +34,7 @@ class CompositeApi:
             "p2_year": p2_year, "p2_hour": p2_hour, "p2_min": p2_min,
             "p2_sec": p2_sec, "p2_gender": p2_gender, "p2_place": p2_place,
             "p2_lat": p2_lat, "p2_lon": p2_lon, "p2_tzone": p2_tzone,
-            "lan": lan, "house_system": house_system,
+            "lan": lan, "house_system": resolve_house_system(house_system),
         }
         d.update(extra)
         return d

{divineapi-1.1.0 → divineapi-1.3.0}/divineapi/western/natal.py

@@ -1,8 +1,9 @@
 """Western API - Natal endpoints (astroapi-4 and astroapi-8)."""
 
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict
 
 from ..client import BaseClient
+from ._house_system import resolve_house_system
 
 
 class NatalApi:
@@ -27,7 +28,7 @@ class NatalApi:
             "full_name": full_name, "day": day, "month": month, "year": year,
             "hour": hour, "min": min, "sec": sec, "gender": gender,
             "place": place, "lat": lat, "lon": lon, "tzone": tzone,
-            "lan": lan, "house_system": house_system,
+            "lan": lan, "house_system": resolve_house_system(house_system),
         }
         d.update(extra)
         return d
@@ -44,11 +45,11 @@ class NatalApi:
 
     def planetary_positions(self, **kw: Any) -> Dict[str, Any]:
         """Natal Planetary Positions."""
-        return self._post4("/western-api/v2/planetary-positions", **kw)
+        return self._post4("/western-api/v1/planetary-positions", **kw)
 
     def house_cusps(self, **kw: Any) -> Dict[str, Any]:
         """Natal House Cusps."""
-        return self._post4("/western-api/v2/house-cusps", **kw)
+        return self._post4("/western-api/v1/house-cusps", **kw)
 
     def aspect_table(self, **kw: Any) -> Dict[str, Any]:
         """Natal Aspect Table."""

{divineapi-1.1.0 → divineapi-1.3.0}/divineapi/western/planet_returns.py

@@ -3,6 +3,7 @@
 from typing import Any, Dict
 
 from ..client import BaseClient
+from ._house_system import resolve_house_system
 
 HOST = "astroapi-8"
 
@@ -25,7 +26,7 @@ class PlanetReturnsApi:
             "full_name": full_name, "day": day, "month": month, "year": year,
             "hour": hour, "min": min, "sec": sec, "gender": gender,
             "place": place, "lat": lat, "lon": lon, "tzone": tzone,
-            "lan": lan, "house_system": house_system,
+            "lan": lan, "house_system": resolve_house_system(house_system),
         }
         d.update(extra)
         return d
@@ -46,14 +47,15 @@ class PlanetReturnsApi:
         return self._c.post(HOST, "/western-api/v1/planet-returns-list", self._birth(**kw))
 
     def planet_return_details(
-        self, planet: str, return_key: str,
+        self, planet: str, return_key: str, return_year: int,
         return_lat: float, return_lon: float,
         return_tzone: float, return_place: str,
         **kw: Any,
     ) -> Dict[str, Any]:
-        """Planet Return Details."""
+        """Planet Return Details (``return_key`` comes from ``planet_return_list``)."""
         kw["planet"] = planet
         kw["return_key"] = return_key
+        kw["return_year"] = return_year
         kw["return_lat"] = return_lat
         kw["return_lon"] = return_lon
         kw["return_tzone"] = return_tzone

{divineapi-1.1.0 → divineapi-1.3.0}/divineapi/western/prenatal.py

@@ -3,6 +3,7 @@
 from typing import Any, Dict
 
 from ..client import BaseClient
+from ._house_system import resolve_house_system
 
 HOST = "astroapi-8"
 
@@ -25,7 +26,7 @@ class PrenatalApi:
             "full_name": full_name, "day": day, "month": month, "year": year,
             "hour": hour, "min": min, "sec": sec, "gender": gender,
             "place": place, "lat": lat, "lon": lon, "tzone": tzone,
-            "lan": lan, "house_system": house_system,
+            "lan": lan, "house_system": resolve_house_system(house_system),
         }
         d.update(extra)
         return d

{divineapi-1.1.0 → divineapi-1.3.0}/divineapi/western/progressions.py

@@ -1,8 +1,9 @@
 """Western API - Progressions endpoints (astroapi-8)."""
 
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 
 from ..client import BaseClient
+from ._house_system import resolve_house_system
 
 HOST = "astroapi-8"
 
@@ -25,7 +26,7 @@ class ProgressionsApi:
             "full_name": full_name, "day": day, "month": month, "year": year,
             "hour": hour, "min": min, "sec": sec, "gender": gender,
             "place": place, "lat": lat, "lon": lon, "tzone": tzone,
-            "lan": lan, "house_system": house_system,
+            "lan": lan, "house_system": resolve_house_system(house_system),
         }
         d.update(extra)
         return d
@@ -48,15 +49,25 @@ class ProgressionsApi:
         return self._c.post(HOST, "/western-api/v1/planetary-arc-directions", self._birth(**kw))
 
     def secondary_progressions(
-        self, planet: str,
+        self,
         progressed_day: int, progressed_month: int, progressed_year: int,
+        progressed_hour: int, progressed_min: int, progressed_sec: int,
         progressed_type: str,
+        planet: Optional[str] = None,
         **kw: Any,
     ) -> Dict[str, Any]:
-        """Secondary Progressions."""
-        kw["planet"] = planet
+        """Secondary Progressions.
+
+        ``progressed_day/month/year/hour/min/sec`` and ``progressed_type`` are
+        required by the API; ``planet`` is optional.
+        """
         kw["progressed_day"] = progressed_day
         kw["progressed_month"] = progressed_month
         kw["progressed_year"] = progressed_year
+        kw["progressed_hour"] = progressed_hour
+        kw["progressed_min"] = progressed_min
+        kw["progressed_sec"] = progressed_sec
         kw["progressed_type"] = progressed_type
+        if planet is not None:
+            kw["planet"] = planet
         return self._c.post(HOST, "/western-api/v1/secondary-progressions", self._birth(**kw))

{divineapi-1.1.0 → divineapi-1.3.0}/divineapi/western/synastry.py

@@ -3,6 +3,7 @@
 from typing import Any, Dict
 
 from ..client import BaseClient
+from ._house_system import resolve_house_system
 
 HOST = "astroapi-4"
 HOST8 = "astroapi-8"
@@ -38,7 +39,7 @@ class SynastryApi:
             "p2_year": p2_year, "p2_hour": p2_hour, "p2_min": p2_min,
             "p2_sec": p2_sec, "p2_gender": p2_gender, "p2_place": p2_place,
             "p2_lat": p2_lat, "p2_lon": p2_lon, "p2_tzone": p2_tzone,
-            "lan": lan, "house_system": house_system,
+            "lan": lan, "house_system": resolve_house_system(house_system),
         }
         d.update(extra)
         return d

divineapi-1.3.0/divineapi/western/transit.py

@@ -0,0 +1,218 @@
+"""Western API - Transit endpoints (astroapi-4 and astroapi-8)."""
+
+from typing import Any, Dict
+
+from ..client import BaseClient
+from ._house_system import resolve_house_system
+
+
+class TransitApi:
+    """Transit endpoints for Western astrology."""
+
+    def __init__(self, client: BaseClient) -> None:
+        self._c = client
+
+    # ------------------------------------------------------------------ #
+    # Payload helpers
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def _birth(
+        full_name: str, day: int, month: int, year: int,
+        hour: int, min: int, sec: int, gender: str,
+        place: str, lat: float, lon: float, tzone: float,
+        lan: str = "en", house_system: str = "placidus",
+        **extra: Any,
+    ) -> Dict[str, Any]:
+        d: Dict[str, Any] = {
+            "full_name": full_name, "day": day, "month": month, "year": year,
+            "hour": hour, "min": min, "sec": sec, "gender": gender,
+            "place": place, "lat": lat, "lon": lon, "tzone": tzone,
+            "lan": lan, "house_system": resolve_house_system(house_system),
+        }
+        d.update(extra)
+        return d
+
+    @staticmethod
+    def _transit_dt(
+        transit_day: int, transit_month: int, transit_year: int,
+        transit_hour: int = 0, transit_min: int = 0, transit_sec: int = 0,
+    ) -> Dict[str, Any]:
+        return {
+            "transit_day": transit_day, "transit_month": transit_month,
+            "transit_year": transit_year, "transit_hour": transit_hour,
+            "transit_min": transit_min, "transit_sec": transit_sec,
+        }
+
+    @staticmethod
+    def _transit_loc(
+        transit_lat: float, transit_lon: float,
+        transit_tzone: float, transit_place: str,
+    ) -> Dict[str, Any]:
+        return {
+            "transit_lat": transit_lat, "transit_lon": transit_lon,
+            "transit_tzone": transit_tzone, "transit_place": transit_place,
+        }
+
+    def _post4(self, path: str, **kw: Any) -> Dict[str, Any]:
+        return self._c.post("astroapi-4", path, self._birth(**kw))
+
+    def _post8(self, path: str, **kw: Any) -> Dict[str, Any]:
+        return self._c.post("astroapi-8", path, self._birth(**kw))
+
+    # ------------------------------------------------------------------ #
+    # astroapi-4 transit endpoints
+    # ------------------------------------------------------------------ #
+
+    def basic(
+        self,
+        transit_day: int, transit_month: int, transit_year: int,
+        transit_hour: int = 0, transit_min: int = 0, transit_sec: int = 0,
+        **kw: Any,
+    ) -> Dict[str, Any]:
+        """Transit Basic. Requires the transit date; time defaults to 00:00:00."""
+        payload = self._birth(**kw)
+        payload.update(self._transit_dt(
+            transit_day, transit_month, transit_year,
+            transit_hour, transit_min, transit_sec,
+        ))
+        return self._c.post("astroapi-4", "/western-api/v1/transit/basic", payload)
+
+    def daily(self, **kw: Any) -> Dict[str, Any]:
+        """Transit Daily."""
+        return self._post4("/western-api/v1/transit/daily", **kw)
+
+    def weekly(self, transit_planet: str, **kw: Any) -> Dict[str, Any]:
+        """Transit Weekly. Requires the transiting planet (e.g. 'moon')."""
+        kw["transit_planet"] = transit_planet
+        return self._post4("/western-api/v1/transit/weekly", **kw)
+
+    def house(
+        self,
+        transit_day: int, transit_month: int, transit_year: int,
+        transit_lat: float, transit_lon: float,
+        transit_tzone: float, transit_place: str,
+        transit_hour: int = 0, transit_min: int = 0, transit_sec: int = 0,
+        **kw: Any,
+    ) -> Dict[str, Any]:
+        """Transit House. Requires transit date + location; time defaults to 00:00:00."""
+        payload = self._birth(**kw)
+        payload.update(self._transit_dt(
+            transit_day, transit_month, transit_year,
+            transit_hour, transit_min, transit_sec,
+        ))
+        payload.update(self._transit_loc(
+            transit_lat, transit_lon, transit_tzone, transit_place,
+        ))
+        return self._c.post("astroapi-4", "/western-api/v1/transit/house", payload)
+
+    # ------------------------------------------------------------------ #
+    # astroapi-8 transit endpoints
+    # ------------------------------------------------------------------ #
+
+    def monthly(
+        self,
+        transit_planet: str, transit_month: int, transit_year: int,
+        transit_lat: float, transit_lon: float,
+        transit_tzone: float, transit_place: str,
+        **kw: Any,
+    ) -> Dict[str, Any]:
+        """Transit Monthly. Requires the transiting planet, month, year and location."""
+        payload = self._birth(**kw)
+        payload.update({
+            "transit_planet": transit_planet,
+            "transit_month": transit_month, "transit_year": transit_year,
+        })
+        payload.update(self._transit_loc(
+            transit_lat, transit_lon, transit_tzone, transit_place,
+        ))
+        return self._c.post("astroapi-8", "/western-api/v2/transit/monthly", payload)
+
+    def full(
+        self,
+        transit_planet: str,
+        transit_day: int, transit_month: int, transit_year: int,
+        transit_lat: float, transit_lon: float,
+        transit_tzone: float, transit_place: str,
+        transit_hour: int = 0, transit_min: int = 0, transit_sec: int = 0,
+        **kw: Any,
+    ) -> Dict[str, Any]:
+        """Full Transit. Requires the transiting planet, transit date and location."""
+        payload = self._birth(**kw)
+        payload["transit_planet"] = transit_planet
+        payload.update(self._transit_dt(
+            transit_day, transit_month, transit_year,
+            transit_hour, transit_min, transit_sec,
+        ))
+        payload.update(self._transit_loc(
+            transit_lat, transit_lon, transit_tzone, transit_place,
+        ))
+        return self._c.post("astroapi-8", "/western-api/v1/full-transit", payload)
+
+    def planet_retrograde(
+        self, planet: str, month: int, year: int,
+        place: str, lat: float, lon: float, tzone: float,
+    ) -> Dict[str, Any]:
+        """Planet Retrograde Transit."""
+        return self._c.post("astroapi-8", "/western-api/v1/planet-retrograde-transit", {
+            "planet": planet, "month": month, "year": year,
+            "place": place, "lat": lat, "lon": lon, "tzone": tzone,
+        })
+
+    def planetary_ingress(
+        self, planet: str, month: int, year: int,
+        place: str, lat: float, lon: float, tzone: float,
+    ) -> Dict[str, Any]:
+        """Planetary Ingress."""
+        return self._c.post("astroapi-8", "/western-api/v1/planetary-ingress", {
+            "planet": planet, "month": month, "year": year,
+            "place": place, "lat": lat, "lon": lon, "tzone": tzone,
+        })
+
+    def planet_combustion(
+        self, planet: str, month: int, year: int,
+        place: str, lat: float, lon: float, tzone: float,
+    ) -> Dict[str, Any]:
+        """Planet Combustion Transit."""
+        return self._c.post("astroapi-8", "/western-api/v1/planet-combustion-transit", {
+            "planet": planet, "month": month, "year": year,
+            "place": place, "lat": lat, "lon": lon, "tzone": tzone,
+        })
+
+    def wheel_chart(
+        self,
+        transit_day: int, transit_month: int, transit_year: int,
+        transit_lat: float, transit_lon: float,
+        transit_tzone: float, transit_place: str,
+        transit_hour: int = 0, transit_min: int = 0, transit_sec: int = 0,
+        **kw: Any,
+    ) -> Dict[str, Any]:
+        """Transit Wheel Chart. Requires transit date + location."""
+        payload = self._birth(**kw)
+        payload.update(self._transit_dt(
+            transit_day, transit_month, transit_year,
+            transit_hour, transit_min, transit_sec,
+        ))
+        payload.update(self._transit_loc(
+            transit_lat, transit_lon, transit_tzone, transit_place,
+        ))
+        return self._c.post("astroapi-8", "/western-api/v1/transit/wheel-chart", payload)
+
+    def planetary_positions(
+        self,
+        transit_day: int, transit_month: int, transit_year: int,
+        transit_lat: float, transit_lon: float,
+        transit_tzone: float, transit_place: str,
+        transit_hour: int = 0, transit_min: int = 0, transit_sec: int = 0,
+        **kw: Any,
+    ) -> Dict[str, Any]:
+        """Transit Planetary Positions. Requires transit date + location."""
+        payload = self._birth(**kw)
+        payload.update(self._transit_dt(
+            transit_day, transit_month, transit_year,
+            transit_hour, transit_min, transit_sec,
+        ))
+        payload.update(self._transit_loc(
+            transit_lat, transit_lon, transit_tzone, transit_place,
+        ))
+        return self._c.post("astroapi-8", "/western-api/v1/transit/planetary-positions", payload)

{divineapi-1.1.0 → divineapi-1.3.0}/divineapi.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: divineapi
-Version: 1.1.0
+Version: 1.3.0
 Summary: Official Python SDK for the Divine API - Astrology, Numerology, Tarot & more
 Author-email: Divine API <support@divineapi.com>
 License: MIT
@@ -51,9 +51,9 @@ from divineapi import DivineApi
 
 client = DivineApi(api_key="your-api-key", auth_token="your-bearer-token")
 
-# Daily Horoscope
+# Daily Horoscope (h_day = today, tomorrow, or yesterday)
 result = client.horoscope.daily(
-    sign="aries", day=10, month=3, year=2024, tzone=5.5
+    sign="aries", h_day="today", tzone=5.5
 )
 print(result)
 ```
@@ -64,10 +64,11 @@ print(result)
 
 ```python
 # Daily / Weekly / Monthly / Yearly Horoscope
-client.horoscope.daily(sign="aries", day=10, month=3, year=2024, tzone=5.5)
-client.horoscope.weekly(sign="leo", week="thisweek", tzone=5.5)
-client.horoscope.monthly(sign="cancer", month=3, tzone=5.5)
-client.horoscope.yearly(sign="virgo", year=2024, tzone=5.5)
+# daily h_day = today / tomorrow / yesterday; weekly/monthly/yearly = current / prev / next
+client.horoscope.daily(sign="aries", h_day="today", tzone=5.5)
+client.horoscope.weekly(sign="leo", week="current", tzone=5.5)
+client.horoscope.monthly(sign="cancer", month="current", tzone=5.5)
+client.horoscope.yearly(sign="virgo", year="current", tzone=5.5)
 
 # Chinese & Numerology Horoscope
 client.horoscope.chinese(sign="rat", h_day="today", tzone=5.5)
@@ -164,8 +165,9 @@ client.indian.festival.chaitra_festivals(
 client.indian.festival.english_calendar(
     year=2024, month=3, place="Delhi", lat=28.6, lon=77.2, tzone=5.5
 )
+# festival is a lowercase snake_case slug from the Divine festival list
 client.indian.festival.find_festival(
-    festival="diwali", year=2024,
+    festival="maha_shivratri", year=2024,
     place="Delhi", lat=28.6, lon=77.2, tzone=5.5
 )
 client.indian.festival.malayalam_festivals(
@@ -174,6 +176,9 @@ client.indian.festival.malayalam_festivals(
 client.indian.festival.tamil_festivals(
     year=2027, place="Chennai", lat=13.0827, lon=80.2707, tzone=5.5
 )
+client.indian.festival.sankranti_festivals(
+    year=2027, place="New Delhi", lat=28.6139, lon=77.2090, tzone=5.5
+)
 ```
 
 ### Western Astrology - Natal
@@ -190,7 +195,7 @@ client.western.natal.house_cusps(**birth_w)
 client.western.natal.aspect_table(**birth_w)
 client.western.natal.natal_wheel_chart(**birth_w)
 client.western.natal.natal_insights(**birth_w)
-client.western.natal.dominants(method="traditional", **birth_w)
+client.western.natal.dominants(method="TRADITIONAL", **birth_w)
 ```
 
 ### Western Astrology - Synastry
@@ -249,7 +254,7 @@ client.lifestyle.astro_chic_picks(sign="virgo", h_day="today", tzone=5.5)
 ### Calculators
 
 ```python
-client.calculators.flames(full_name="John", partner_name="Jane")
+client.calculators.flames(your_name="John", partner_name="Jane")
 client.calculators.love_calculator(
     your_name="John", partner_name="Jane",
     your_gender="male", partner_gender="female",
@@ -259,11 +264,15 @@ client.calculators.love_calculator(
 ### PDF Reports
 
 ```python
+# The six branding fields (company_url, logo_url, footer_text, company_name,
+# company_email, company_bio) are REQUIRED by the PDF backend.
 client.pdf.kundali_sampoorna(
     full_name="John", day=1, month=1, year=1990,
     hour=10, min=30, sec=0, gender="male",
     place="Mumbai", lat=19.07, lon=72.87, tzone=5.5,
     company_name="AstroCo", company_url="https://example.com",
+    company_email="hello@example.com", company_bio="We do astrology.",
+    logo_url="https://example.com/logo.png", footer_text="(c) AstroCo",
 )
 ```
 
@@ -275,7 +284,7 @@ from divineapi import DivineApi, AuthenticationError, ValidationError, RateLimit
 client = DivineApi(api_key="...", auth_token="...")
 
 try:
-    result = client.horoscope.daily(sign="aries", day=10, month=3, year=2024, tzone=5.5)
+    result = client.horoscope.daily(sign="aries", h_day="today", tzone=5.5)
 except AuthenticationError as e:
     print(f"Auth failed: {e}")
 except ValidationError as e:
@@ -288,7 +297,7 @@ except RateLimitError as e:
 
 ```python
 with DivineApi(api_key="...", auth_token="...") as client:
-    result = client.horoscope.daily(sign="aries", day=10, month=3, year=2024, tzone=5.5)
+    result = client.horoscope.daily(sign="aries", h_day="today", tzone=5.5)
 ```
 
 ## Configuration

{divineapi-1.1.0 → divineapi-1.3.0}/divineapi.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ divineapi/indian/kundli.py
 divineapi/indian/match_making.py
 divineapi/indian/panchang.py
 divineapi/western/__init__.py
+divineapi/western/_house_system.py
 divineapi/western/composite.py
 divineapi/western/natal.py
 divineapi/western/planet_returns.py

{divineapi-1.1.0 → divineapi-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "divineapi"
-version = "1.1.0"
+version = "1.3.0"
 description = "Official Python SDK for the Divine API - Astrology, Numerology, Tarot & more"
 readme = "README.md"
 license = {text = "MIT"}

divineapi-1.1.0/divineapi/western/transit.py

@@ -1,110 +0,0 @@
-"""Western API - Transit endpoints (astroapi-4 and astroapi-8)."""
-
-from typing import Any, Dict
-
-from ..client import BaseClient
-
-
-class TransitApi:
-    """Transit endpoints for Western astrology."""
-
-    def __init__(self, client: BaseClient) -> None:
-        self._c = client
-
-    # ------------------------------------------------------------------ #
-    # Birth-data helper
-    # ------------------------------------------------------------------ #
-
-    @staticmethod
-    def _birth(
-        full_name: str, day: int, month: int, year: int,
-        hour: int, min: int, sec: int, gender: str,
-        place: str, lat: float, lon: float, tzone: float,
-        lan: str = "en", house_system: str = "placidus",
-        **extra: Any,
-    ) -> Dict[str, Any]:
-        d: Dict[str, Any] = {
-            "full_name": full_name, "day": day, "month": month, "year": year,
-            "hour": hour, "min": min, "sec": sec, "gender": gender,
-            "place": place, "lat": lat, "lon": lon, "tzone": tzone,
-            "lan": lan, "house_system": house_system,
-        }
-        d.update(extra)
-        return d
-
-    def _post4(self, path: str, **kw: Any) -> Dict[str, Any]:
-        return self._c.post("astroapi-4", path, self._birth(**kw))
-
-    def _post8(self, path: str, **kw: Any) -> Dict[str, Any]:
-        return self._c.post("astroapi-8", path, self._birth(**kw))
-
-    # ------------------------------------------------------------------ #
-    # astroapi-4 transit endpoints
-    # ------------------------------------------------------------------ #
-
-    def basic(self, **kw: Any) -> Dict[str, Any]:
-        """Transit Basic (pass transit_day/month/year/hour/min/sec via **kw)."""
-        return self._post4("/western-api/v1/transit/basic", **kw)
-
-    def daily(self, **kw: Any) -> Dict[str, Any]:
-        """Transit Daily."""
-        return self._post4("/western-api/v1/transit/daily", **kw)
-
-    def weekly(self, transit_planet: str, **kw: Any) -> Dict[str, Any]:
-        """Transit Weekly."""
-        kw["transit_planet"] = transit_planet
-        return self._post4("/western-api/v1/transit/weekly", **kw)
-
-    def house(self, **kw: Any) -> Dict[str, Any]:
-        """Transit House (pass full transit params via **kw)."""
-        return self._post4("/western-api/v1/transit/house", **kw)
-
-    # ------------------------------------------------------------------ #
-    # astroapi-8 transit endpoints
-    # ------------------------------------------------------------------ #
-
-    def monthly(self, **kw: Any) -> Dict[str, Any]:
-        """Transit Monthly (pass extensive transit params via **kw)."""
-        return self._post8("/western-api/v2/transit/monthly", **kw)
-
-    def full(self, **kw: Any) -> Dict[str, Any]:
-        """Full Transit (pass extensive transit params via **kw)."""
-        return self._post8("/western-api/v1/full-transit", **kw)
-
-    def planet_retrograde(
-        self, planet: str, month: int, year: int,
-        place: str, lat: float, lon: float, tzone: float,
-    ) -> Dict[str, Any]:
-        """Planet Retrograde Transit."""
-        return self._c.post("astroapi-8", "/western-api/v1/planet-retrograde-transit", {
-            "planet": planet, "month": month, "year": year,
-            "place": place, "lat": lat, "lon": lon, "tzone": tzone,
-        })
-
-    def planetary_ingress(
-        self, planet: str, month: int, year: int,
-        place: str, lat: float, lon: float, tzone: float,
-    ) -> Dict[str, Any]:
-        """Planetary Ingress."""
-        return self._c.post("astroapi-8", "/western-api/v1/planetary-ingress", {
-            "planet": planet, "month": month, "year": year,
-            "place": place, "lat": lat, "lon": lon, "tzone": tzone,
-        })
-
-    def planet_combustion(
-        self, planet: str, month: int, year: int,
-        place: str, lat: float, lon: float, tzone: float,
-    ) -> Dict[str, Any]:
-        """Planet Combustion Transit."""
-        return self._c.post("astroapi-8", "/western-api/v1/planet-combustion-transit", {
-            "planet": planet, "month": month, "year": year,
-            "place": place, "lat": lat, "lon": lon, "tzone": tzone,
-        })
-
-    def wheel_chart(self, **kw: Any) -> Dict[str, Any]:
-        """Transit Wheel Chart."""
-        return self._post8("/western-api/v1/transit/wheel-chart", **kw)
-
-    def planetary_positions(self, **kw: Any) -> Dict[str, Any]:
-        """Transit Planetary Positions."""
-        return self._post8("/western-api/v1/transit/planetary-positions", **kw)