@roxyapi/sdk 1.2.69 → 1.2.71

package/AGENTS.md

@@ -1,6 +1,6 @@
 # @roxyapi/sdk - Agent Guide
 
-TypeScript SDK for RoxyAPI. 12+ domains (Western astrology, Vedic astrology, numerology, tarot, human design, forecast, biorhythm, I Ching, crystals, dreams, angel numbers, location) plus utility namespaces (usage, languages). One API key, fully typed, zero runtime dependencies.
+TypeScript SDK for RoxyAPI. 14+ domains (Western astrology, Vedic astrology, forecast, human design, Chinese astrology, feng shui, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers, location) plus utility namespaces (usage, languages). One API key, fully typed, zero runtime dependencies.
 
 > Before writing any code with this SDK, read `docs/llms-full.txt` in this package for the complete method reference with examples.
 
@@ -45,6 +45,8 @@ Type `roxy.` to see all available namespaces. Type `roxy.{domain}.` to see every
 | `roxy.vedicAstrology` | Vedic astrology (Jyotish) and KP API for kundli generation with 15 divisional charts (D1-D60), Ashtakoot Gun Milan ku... |
 | `roxy.forecast` | Forecast API that merges upcoming transit aspects, sign ingresses, retrograde stations, new and full moons, biorhythm... |
 | `roxy.humanDesign` | Generate the full Human Design bodygraph from a birth moment: type, strategy, inner authority, profile, definition, i... |
+| `roxy.chineseAstrology` | Calculate BaZi Four Pillars charts, Chinese zodiac signs, and the Chinese lunisolar calendar from any birth moment: y... |
+| `roxy.fengShui` | Compute classical feng shui from one API: Xuan Kong flying star natal charts for any of the nine periods and 24 mount... |
 | `roxy.numerology` | Numerology API to calculate life path, expression, soul urge, personality, and maturity numbers, with Pinnacle and Ch... |
 | `roxy.tarot` | Tarot reading API with the complete 78-card Rider-Waite-Smith deck and card meanings for love, career, health, and sp... |
 | `roxy.biorhythm` | The most complete biorhythm API: 10 cycle types across 3 primary (physical, emotional, intellectual), 4 secondary (in... |
@@ -57,7 +59,7 @@ Type `roxy.` to see all available namespaces. Type `roxy.{domain}.` to see every
 | `roxy.languages` | List the response languages accepted by the `lang` query parameter on every i18n-aware endpoint |
 <!-- END:DOMAINS -->
 
-**Total:** 160+ endpoints across 12+ product domains plus usage and languages. The table above auto-syncs from `specs/openapi.json` at release time.
+**Total:** 209+ endpoints across 14+ product domains plus usage and languages. The table above auto-syncs from `specs/openapi.json` at release time.
 
 ## Quality guidelines for agents
 
@@ -120,7 +122,7 @@ await roxy.numerology.calculateLifePath({
 });
 ```
 
-Supported: `astrology`, `vedicAstrology`, `numerology`, `tarot`, `biorhythm`, `iching`, `crystals`, `angelNumbers`. English-only: `dreams`, `location`, `usage`, `languages`. To list supported codes at runtime, call `roxy.languages.listLanguages()`.
+Supported: `astrology`, `vedicAstrology`, `forecast`, `humanDesign`, `chineseAstrology`, `fengShui`, `numerology`, `tarot`, `biorhythm`, `iching`, `crystals`, `angelNumbers`. English-only: `dreams`, `location`, `usage`, `languages`. The two Chinese scripts (`zh-Hans`, `zh-Hant`) currently ship on Chinese astrology and feng shui; every other domain answers those codes in English per field. To list supported codes at runtime, call `roxy.languages.listLanguages()`.
 
 ### Error handling
 
@@ -151,7 +153,7 @@ console.log(data.sign, data.overview);
 
 ## Common tasks
 
-Ordered by domain priority (Western, Vedic, Numerology, Tarot, Biorhythm, I Ching, Crystals, Dreams, Angel Numbers, Location, Usage, Languages).
+Ordered by domain priority (Western, Vedic, Forecast, Human Design, Chinese Astrology, Feng Shui, Numerology, Tarot, Biorhythm, I Ching, Crystals, Dreams, Angel Numbers, Location, Usage, Languages).
 
 | Task | Code |
 |------|------|

package/README.md

@@ -15,7 +15,7 @@ TypeScript SDK for astrology, Vedic astrology, numerology, tarot, and more.
 
 One API key. Fully typed. Verified against NASA JPL Horizons.
 
-The fastest way to add natal charts, daily horoscopes, synastry, Vedic kundli, tarot spreads, numerology, human design bodygraphs, and transit forecasts to Node.js apps, backends, and AI agents. 12+ domains behind a single [Roxy](https://roxyapi.com) subscription, interpretations in eight languages.
+The fastest way to add natal charts, daily horoscopes, synastry, Vedic kundli, tarot spreads, numerology, human design bodygraphs, and transit forecasts to Node.js apps, backends, and AI agents. 14+ domains behind a single [Roxy](https://roxyapi.com) subscription, interpretations in 10+ languages.
 
 ## Install
 
@@ -89,6 +89,8 @@ const { latitude, longitude, timezone } = data.cities[0];
 | `roxy.vedicAstrology` | Vedic astrology (Jyotish) and KP API for kundli generation with 15 divisional charts (D1-D60), Ashtakoot Gun Milan ku... |
 | `roxy.forecast` | Forecast API that merges upcoming transit aspects, sign ingresses, retrograde stations, new and full moons, biorhythm... |
 | `roxy.humanDesign` | Generate the full Human Design bodygraph from a birth moment: type, strategy, inner authority, profile, definition, i... |
+| `roxy.chineseAstrology` | Calculate BaZi Four Pillars charts, Chinese zodiac signs, and the Chinese lunisolar calendar from any birth moment: y... |
+| `roxy.fengShui` | Compute classical feng shui from one API: Xuan Kong flying star natal charts for any of the nine periods and 24 mount... |
 | `roxy.numerology` | Numerology API to calculate life path, expression, soul urge, personality, and maturity numbers, with Pinnacle and Ch... |
 | `roxy.tarot` | Tarot reading API with the complete 78-card Rider-Waite-Smith deck and card meanings for love, career, health, and sp... |
 | `roxy.biorhythm` | The most complete biorhythm API: 10 cycle types across 3 primary (physical, emotional, intellectual), 4 secondary (in... |
@@ -259,7 +261,54 @@ const { data: timeline } = await roxy.forecast.generateTimeline({
 // timeline.events[0].date, timeline.events[0].domain, timeline.events[0].description, timeline.events[0].significance
 ```
 
-### 7. Biorhythm API (daily check-in, forecast, compatibility)
+### 7. Chinese astrology API (BaZi four pillars, zodiac sign)
+
+BaZi (Four Pillars of Destiny), the twelve-animal zodiac, and the lunisolar calendar with its almanac. The school splits that make two calculators disagree are typed request parameters with named defaults, echoed back in a `conventions` object on every response, so a chart can be reproduced rather than guessed at. The zodiac routes answer the high-volume consumer questions; BaZi and the almanac are where an app goes deeper.
+
+```typescript
+// BaZi Four Pillars. The anchor call: the rest of the domain reads off these four pillars.
+// `timezone` takes the IANA name, resolved to the DST-correct offset for the birth date.
+const { data: bazi } = await roxy.chineseAstrology.generateBaziChart({
+  body: { date: '1990-07-04', time: '10:12:00', timezone: 'America/New_York' },
+});
+// bazi.pillars[n].position ('year' | 'month' | 'day' | 'hour'), .stem.element, .branch.animal
+// bazi.pillars[n].tenGod.name, .hiddenStems, .naYin
+// bazi.dayMaster.element, bazi.zodiacAnimal, bazi.fiveElements, bazi.conventions, bazi.summary
+
+// Chinese zodiac sign. Defaults `yearBoundary` to 'lunar-new-year', the folk rule people mean
+// when they say which animal they are. Pass 'li-chun' to match the classical BaZi boundary.
+const { data: sign } = await roxy.chineseAstrology.calculateZodiacAnimal({
+  body: { date: '1990-07-04' },
+});
+// sign.animal.name ('Horse'), sign.animal.element ('Fire'), sign.animal.polarity
+// sign.element is the YEAR STEM element ('Metal'), not the element of the animal
+// sign.yearPillar, sign.interpretation
+```
+
+### 8. Feng shui API (Kua number, flying star chart)
+
+Kua numbers with the full Eight Mansions map ranked best to worst, Xuan Kong flying star natal charts for any of the nine periods and 24 mountains, annual and monthly star plates, and the four annual afflictions with exact degree spans. Chinese years resolve at Li Chun, computed astronomically rather than assumed, so the annual charts change over on the real boundary.
+
+```typescript
+// Kua number: one birth date and a gender gives the personal directions everything else reads off.
+const { data: kua } = await roxy.fengShui.calculateKuaNumber({
+  body: { date: '1990-07-04', gender: 'female' },
+});
+// kua.kua (8), kua.group ('east' | 'west'), kua.trigram.english ('Mountain')
+// kua.sectors[n].direction, .starName, .nature ('auspicious' | 'inauspicious'), .rank, .domain
+
+// Flying star natal chart. Period plus facing gives the nine palaces with base, mountain
+// and water stars. Send `facing` (a mountain id like 'bing' or a compass label like 'S2')
+// or `facingDegrees`, not neither.
+const { data: chart } = await roxy.fengShui.generateFlyingStarChart({
+  body: { period: 9, facing: 'S2' },
+});
+// chart.facing.label ('S2'), chart.sitting.label, chart.structure.name ('Double Star at Sitting')
+// chart.palaces[n].palace, .base, .mountain, .water, .reading
+// chart.mountainCenterStar, chart.waterCenterStar, chart.straddling
+```
+
+### 9. Biorhythm API (daily check-in, forecast, compatibility)
 
 Zero competition domain. Steady search volume with the top Google result being a static calculator page. Pure land-grab for wellness, productivity, sports, and couples apps.
 
@@ -275,7 +324,7 @@ const { data: forecast } = await roxy.biorhythm.getForecast({
 });
 ```
 
-### 8. I Ching API (daily hexagram, coin cast, 64-hexagram catalog)
+### 10. I Ching API (daily hexagram, coin cast, 64-hexagram catalog)
 
 Meditation apps, decision-making tools, and wisdom chatbots. `i ching API` and `hexagram API` are the keywords.
 
@@ -289,7 +338,7 @@ const { data: hexagrams } = await roxy.iching.listHexagrams({});
 // hexagrams.hexagrams has 64 entries
 ```
 
-### 9. Crystals API (by zodiac, by chakra, birthstone)
+### 11. Crystals API (by zodiac, by chakra, birthstone)
 
 Crystal retail and metaphysical shops use these to build "crystals for [sign]" and "[chakra] chakra stones" pages.
 
@@ -305,7 +354,7 @@ const { data: byChakra } = await roxy.crystals.getCrystalsByChakra({ path: { cha
 const { data: birthstone } = await roxy.crystals.getBirthstones({ path: { month: 4 } });
 ```
 
-### 10. Dream interpretation API (symbol dictionary, search)
+### 12. Dream interpretation API (symbol dictionary, search)
 
 Thousands of dream symbols. `dream meaning` is among the highest-volume spiritual searches on Google. Journal apps, AI therapy chatbots, and self-discovery products are the buyers.
 
@@ -319,7 +368,7 @@ const { data: results } = await roxy.dreams.searchDreamSymbols({ query: { q: 'fl
 // results.symbols is an array of matching symbols
 ```
 
-### 11. Angel Numbers API (1111, 222, 333 meanings plus universal lookup)
+### 13. Angel Numbers API (1111, 222, 333 meanings plus universal lookup)
 
 Gen Z spiritual-tok fuel. `111 meaning`, `222 meaning`, `333 angel number` are evergreen viral queries with massive shareability.
 
@@ -381,7 +430,7 @@ const roxy = new Roxy({ client });
 
 ## Multi-language responses
 
-Interpretations and editorial text are available in eight languages: English (`en`), Turkish (`tr`), German (`de`), Spanish (`es`), French (`fr`), Hindi (`hi`), Portuguese (`pt`), Russian (`ru`). Pass `query: { lang }` on any supported endpoint:
+Interpretations and editorial text are available in 10 languages: English (`en`), Turkish (`tr`), German (`de`), Spanish (`es`), French (`fr`), Hindi (`hi`), Portuguese (`pt`), Russian (`ru`), Chinese Simplified (`zh-Hans`), Chinese Traditional (`zh-Hant`). Pass `query: { lang }` on any supported endpoint:
 
 ```typescript
 const { data } = await roxy.tarot.getDailyCard({
@@ -390,7 +439,7 @@ const { data } = await roxy.tarot.getDailyCard({
 });
 ```
 
-Supported: `astrology`, `vedicAstrology`, `numerology`, `tarot`, `biorhythm`, `iching`, `crystals`, `angelNumbers`. English-only: `dreams`, `location`, `usage`. Untranslated fields fall back to English.
+Supported: `astrology`, `vedicAstrology`, `forecast`, `humanDesign`, `chineseAstrology`, `fengShui`, `numerology`, `tarot`, `biorhythm`, `iching`, `crystals`, `angelNumbers`. English-only: `dreams`, `location`, `usage`. The two Chinese scripts (`zh-Hans`, `zh-Hant`) currently ship on Chinese astrology and feng shui; every other domain answers those codes in English per field. Untranslated fields fall back to English.
 
 ## Error handling