@roxyapi/sdk 1.2.13 → 1.2.15

package/AGENTS.md

@@ -26,7 +26,7 @@ Every chart, horoscope, panchang, dasha, dosha, navamsa, KP, synastry, compatibi
 const { data } = await roxy.location.searchCities({ query: { q: 'Mumbai' } });
 const { latitude, longitude, utcOffset } = data.cities[0];
 // Use `utcOffset` (decimal: 5.5, -5, 9, ...) as the `timezone` number on chart calls.
-// The city's `timezone` field is the IANA string ("Asia/Kolkata") — not what chart endpoints expect.
+// The city's `timezone` field is the IANA string ("Asia/Kolkata"), not what chart endpoints expect.
 ```
 
 ## Domains
@@ -38,13 +38,13 @@ Type `roxy.` to see all available namespaces. Type `roxy.{domain}.` to see every
 |-----------|-----------|----------------|
 | `roxy.astrology` | 22 | Western astrology: natal charts, horoscopes, synastry, moon phases, transits, compatibility |
 | `roxy.vedicAstrology` | 42 | Vedic/Jyotish: birth charts, dashas, nakshatras, panchang, KP system, doshas, yogas |
-| `roxy.tarot` | 10 | Rider-Waite-Smith deck: spreads, daily pulls, yes/no, Celtic Cross, custom layouts |
 | `roxy.numerology` | 16 | Life path, expression, soul urge, personal year, karmic analysis, compatibility |
-| `roxy.dreams` | 5 | Dream symbol dictionary and interpretations |
-| `roxy.angelNumbers` | 4 | Angel number meanings, pattern analysis, daily guidance |
+| `roxy.tarot` | 10 | Rider-Waite-Smith deck: spreads, daily pulls, yes/no, Celtic Cross, custom layouts |
+| `roxy.biorhythm` | 6 | 10-cycle biorhythm readings, forecasts, critical days, compatibility, daily check-ins (wellness, dating, productivity) |
 | `roxy.iching` | 9 | I Ching: hexagrams, trigrams, coin casting, daily readings |
 | `roxy.crystals` | 12 | Crystal healing properties, zodiac/chakra pairings, birthstones, search |
-| `roxy.biorhythm` | 6 | 10-cycle biorhythm readings, forecasts, critical days, compatibility, daily check-ins (wellness, dating, productivity) |
+| `roxy.dreams` | 5 | Dream symbol dictionary and interpretations |
+| `roxy.angelNumbers` | 4 | Angel number meanings, pattern analysis, daily guidance |
 | `roxy.location` | 3 | City geocoding for birth chart coordinates |
 | `roxy.usage` | 1 | API usage stats and subscription info |
 <!-- END:DOMAINS -->
@@ -57,10 +57,10 @@ Type `roxy.` to see all available namespaces. Type `roxy.{domain}.` to see every
 
 ```typescript
 const { data } = await roxy.location.searchCities({ query: { q: 'Delhi' } });
-const { latitude, longitude, utcOffset } = data.cities[0];
+const { latitude, longitude, timezone } = data.cities[0];
 
 const { data: chart } = await roxy.astrology.generateNatalChart({
-  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone: utcOffset },
+  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone },
 });
 ```
 
@@ -179,7 +179,7 @@ These are the fields AI agents most often get wrong. Copy the format column exac
 
 | Field | Format | Good | Bad |
 |-------|--------|------|-----|
-| `timezone` | Decimal hours from UTC (number) | `5.5` (India IST, GMT+5:30), `5.75` (Nepal NPT, GMT+5:45), `-5` (NY EST), `9.5` (Adelaide), `0` (UTC) | `"5:30"`, `"5:45"`, `5.45`, `"GMT-5"`, `"Asia/Kolkata"`, `"+0530"` |
+| `timezone` | Decimal hours (number) OR IANA string | `5.5`, `-5`, `0` (decimal) OR `"Asia/Kolkata"`, `"America/New_York"` (IANA, resolved to DST-correct offset for the chart date) | `"5:30"`, `"+0530"`, `"GMT-5"`, partial names |
 | `date` | ISO date string | `"1990-01-15"` | `"Jan 15 1990"`, `new Date()`, `"15/01/1990"`, `"1990-1-15"` |
 | `time` | 24-hour string | `"14:30:00"`, `"09:00:00"` | `"2:30 PM"`, `"14:30"` (no seconds), `"9:0:0"` (no leading zeros) |
 | `latitude` | Decimal degrees (number) | `28.6139` (Delhi), `-33.8688` (Sydney), `40.7128` (NYC) | `"28°36'N"`, `"28 36 50"`, strings |
@@ -216,6 +216,20 @@ These are the fields AI agents most often get wrong. Copy the format column exac
 
 DST matters. If the birth date falls inside a daylight-saving window, use the summer / DST offset. For Vedic endpoints this is rarely an issue (most users are in India, fixed 5.5), but Western natal charts must respect DST at the time of birth.
 
+## Astrology domain gotchas for LLMs
+
+LLMs hallucinate confidently in this category. These are the specific traps you will hit when writing client code:
+
+- **Ayanamsa is server-side in Vedic.** LLMs default to tropical / Western math. Vedic endpoints apply sidereal Lahiri ayanamsa server-side. KP endpoints accept `ayanamsa` of `kp-newcomb` (default), `kp-old`, `lahiri`, or `custom`. Do not try to "correct" server output by subtracting ayanamsa in client code.
+- **Tithi count is 30, not 2.** 15 Shukla (waxing) plus 15 Krishna (waning). Older LLM training data conflates Purnima and Amavasya as single tithis. Our panchang response carries a `paksha` field (`"Shukla"` or `"Krishna"`) plus a tithi number, so there are 30 distinct tithis in a lunar month.
+- **Rahu and Ketu are shadow points, not planets.** They do not appear in a real ephemeris. Endpoints accept `nodeType` of `true-node` or `mean-node` to select which calculation to use.
+- **Nakshatra count is 27.** Abhijit is sometimes treated as a 28th in some schools, but this API uses the standard 27. `roxy.vedicAstrology.listNakshatras()` returns an array of length 27.
+- **Retrograde is per-planet, not global.** Natal chart planets and Vedic `meta` include `isRetrograde: boolean` per planet. KP planet lists use `retrograde`. Never generate "Mercury retrograde globally" UI copy, check the specific planet in the response.
+- **Tarot reversals are a product choice.** `allowReversals: false` on a tarot draw means no reversed cards in that draw, period. It is not cosmically meaningful, it is a config flag.
+- **Angel number lookup works for any positive integer.** Digit-root fallback covers non-canonical numbers. Do not generate validation logic that rejects anything other than `111` / `222` / `333`.
+- **Seed-based daily endpoints are DETERMINISTIC per `(seed, date)` pair.** Same seed plus same date returns the same reading. This is by design for push-notification consistency. Do not describe it as "cached" or retry on stale responses.
+- **Timezone affects Western calculations more than Vedic.** Western natal charts must respect DST at time of birth. Vedic endpoints default to IST (`5.5`) which is DST-free. Use `utcOffset` from the Location API response as your `timezone` value, not the user's current clock.
+
 ## MCP equivalents
 
 Every method has a matching MCP tool. The remote MCP server per domain is at `https://roxyapi.com/mcp/{domain}` (Streamable HTTP, no stdio / no self-hosting). Tool names follow `{method}_{path_snake_case}`, for example:

package/README.md

@@ -28,16 +28,18 @@ const roxy = createRoxy(process.env.ROXY_API_KEY!);
 const { data } = await roxy.location.searchCities({
   query: { q: 'Mumbai, India' },
 });
-const { latitude, longitude, utcOffset } = data.cities[0];
+const { latitude, longitude, timezone } = data.cities[0];
 
-// Step 2: Western natal chart. Pass utcOffset as the `timezone` number.
+// Step 2: Western natal chart. `timezone` can be the IANA string from the
+// location response — the server resolves it to the DST-correct offset for
+// the chart's own date.
 const { data: chart } = await roxy.astrology.generateNatalChart({
-  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone: utcOffset },
+  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone },
 });
 
 // Vedic kundli uses the same inputs (timezone optional, defaults to 5.5 IST)
 const { data: kundli } = await roxy.vedicAstrology.generateBirthChart({
-  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone: utcOffset },
+  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone },
 });
 ```
 
@@ -49,10 +51,10 @@ Every chart, horoscope, panchang, dasha, dosha, navamsa, KP, synastry, compatibi
 
 ```typescript
 const { data } = await roxy.location.searchCities({ query: { q: 'Tokyo' } });
-const { latitude, longitude, utcOffset } = data.cities[0];
-// Pass utcOffset (5.5, -5, 9, ...) as `timezone` to astrology endpoints.
-// The `timezone` field on the city is the IANA string ("Asia/Tokyo"), keep
-// that for your own date formatting, not for RoxyAPI chart calls.
+const { latitude, longitude, timezone } = data.cities[0];
+// `timezone` is the IANA string ("Asia/Tokyo"). Pass it straight into any
+// chart endpoint — the server resolves it to the DST-correct offset for the
+// chart's date. If you prefer a decimal, `data.cities[0].utcOffset` also works.
 ```
 
 ## Domains
@@ -62,13 +64,13 @@ const { latitude, longitude, utcOffset } = data.cities[0];
 |-----------|-----------|----------------|
 | `roxy.astrology` | 22 | Western astrology: natal charts, horoscopes, synastry, moon phases |
 | `roxy.vedicAstrology` | 42 | Vedic/Jyotish: birth charts, dashas, nakshatras, panchang, KP system |
-| `roxy.tarot` | 10 | 78-card readings: spreads, daily pulls, yes/no, Celtic Cross |
 | `roxy.numerology` | 16 | Life path, expression, soul urge, personal year, karmic lessons |
-| `roxy.dreams` | 5 | Dream symbol dictionary: 3,000+ interpretations |
-| `roxy.angelNumbers` | 4 | Angel number lookup, pattern analysis, daily guidance |
+| `roxy.tarot` | 10 | 78-card readings: spreads, daily pulls, yes/no, Celtic Cross |
+| `roxy.biorhythm` | 6 | 10-cycle biorhythm readings, forecasts, critical days, compatibility |
 | `roxy.iching` | 9 | I Ching hexagrams, trigrams, daily readings |
 | `roxy.crystals` | 12 | Crystal meanings, healing properties, zodiac and chakra pairings |
-| `roxy.biorhythm` | 6 | 10-cycle biorhythm readings, forecasts, critical days, compatibility |
+| `roxy.dreams` | 5 | Dream symbol dictionary: 3,000+ interpretations |
+| `roxy.angelNumbers` | 4 | Angel number lookup, pattern analysis, daily guidance |
 | `roxy.location` | 3 | City and country search for birth chart coordinates |
 | `roxy.usage` | 1 | API usage stats, rate limits, subscription info |
 <!-- END:DOMAINS -->