@roxyapi/sdk 1.2.70 → 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.
 
@@ -59,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
 
@@ -122,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
 
@@ -153,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
 
@@ -261,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.
 
@@ -277,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.
 
@@ -291,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.
 
@@ -307,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.
 
@@ -321,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.
 
@@ -383,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({
@@ -392,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
 

package/dist/factory.cjs

@@ -4011,7 +4011,7 @@ var Roxy = class _Roxy extends HeyApiClient {
 };
 
 // src/version.ts
-var VERSION = "1.2.70";
+var VERSION = "1.2.71";
 
 // src/factory.ts
 function createRoxy(auth) {

package/dist/factory.js

@@ -3188,7 +3188,7 @@ var Roxy = class _Roxy extends HeyApiClient {
 };
 
 // src/version.ts
-var VERSION = "1.2.70";
+var VERSION = "1.2.71";
 
 // src/factory.ts
 function createRoxy(auth) {

package/dist/types.gen.d.ts

@@ -35421,7 +35421,7 @@ export type GetChineseAstrologyCalendarDayByDateResponses = {
              */
             nameLocalized?: string;
             /**
-             * English display name of the officer.
+             * English display name of the officer. Canonical, identical in every language, so it stays safe to compare against in code. The translation is in nameLocalized.
              */
             name: string;
             /**
@@ -35447,9 +35447,13 @@ export type GetChineseAstrologyCalendarDayByDateResponses = {
              */
             number: number;
             /**
-             * English display name of the mansion.
+             * English display name of the mansion. Canonical, identical in every language. The translation is in nameLocalized. Note the mansion has no string id: number is the stable 1 to 28 key, because five of the 28 share a pinyin spelling.
              */
             name: string;
+            /**
+             * Display name of the mansion in the requested language. Absent when lang is en, and absent when a language has no entry for this mansion, so a caller falls back to name rather than rendering a blank.
+             */
+            nameLocalized?: string;
             /**
              * The mansion in Chinese. A data field, identical in every language.
              */
@@ -35467,9 +35471,13 @@ export type GetChineseAstrologyCalendarDayByDateResponses = {
              */
             planet: string;
             /**
-             * Animal emblem of the mansion, the third character of its full Chinese name.
+             * Animal emblem of the mansion, the third character of its full Chinese name. English and canonical, identical in every language, matching how clashAnimal behaves on the same response. The translation is in animalLocalized.
              */
             animal: string;
+            /**
+             * Animal emblem in the requested language. Absent when lang is en, and absent when a language has no entry, so a caller falls back to animal.
+             */
+            animalLocalized?: string;
         };
         /**
          * The zodiac animal the day clashes with, which is the animal six branches away from the day branch. Anyone born in that animal year traditionally avoids the day for anything important.
@@ -35790,7 +35798,7 @@ export type GetChineseAstrologyCalendarMonthlyResponses = {
                  */
                 nameLocalized?: string;
                 /**
-                 * English display name of the officer.
+                 * English display name of the officer. Canonical, identical in every language, so it stays safe to compare against in code. The translation is in nameLocalized.
                  */
                 name: string;
                 /**
@@ -35816,9 +35824,13 @@ export type GetChineseAstrologyCalendarMonthlyResponses = {
                  */
                 number: number;
                 /**
-                 * English display name of the mansion.
+                 * English display name of the mansion. Canonical, identical in every language. The translation is in nameLocalized. Note the mansion has no string id: number is the stable 1 to 28 key, because five of the 28 share a pinyin spelling.
                  */
                 name: string;
+                /**
+                 * Display name of the mansion in the requested language. Absent when lang is en, and absent when a language has no entry for this mansion, so a caller falls back to name rather than rendering a blank.
+                 */
+                nameLocalized?: string;
                 /**
                  * The mansion in Chinese. A data field, identical in every language.
                  */
@@ -35836,9 +35848,13 @@ export type GetChineseAstrologyCalendarMonthlyResponses = {
                  */
                 planet: string;
                 /**
-                 * Animal emblem of the mansion, the third character of its full Chinese name.
+                 * Animal emblem of the mansion, the third character of its full Chinese name. English and canonical, identical in every language, matching how clashAnimal behaves on the same response. The translation is in animalLocalized.
                  */
                 animal: string;
+                /**
+                 * Animal emblem in the requested language. Absent when lang is en, and absent when a language has no entry, so a caller falls back to animal.
+                 */
+                animalLocalized?: string;
             };
             /**
              * The zodiac animal the day clashes with, which is the animal six branches away from the day branch. Anyone born in that animal year traditionally avoids the day for anything important.
@@ -36163,7 +36179,7 @@ export type PostChineseAstrologyCalendarAuspiciousDaysResponses = {
                  */
                 nameLocalized?: string;
                 /**
-                 * English display name of the officer.
+                 * English display name of the officer. Canonical, identical in every language, so it stays safe to compare against in code. The translation is in nameLocalized.
                  */
                 name: string;
                 /**
@@ -36189,9 +36205,13 @@ export type PostChineseAstrologyCalendarAuspiciousDaysResponses = {
                  */
                 number: number;
                 /**
-                 * English display name of the mansion.
+                 * English display name of the mansion. Canonical, identical in every language. The translation is in nameLocalized. Note the mansion has no string id: number is the stable 1 to 28 key, because five of the 28 share a pinyin spelling.
                  */
                 name: string;
+                /**
+                 * Display name of the mansion in the requested language. Absent when lang is en, and absent when a language has no entry for this mansion, so a caller falls back to name rather than rendering a blank.
+                 */
+                nameLocalized?: string;
                 /**
                  * The mansion in Chinese. A data field, identical in every language.
                  */
@@ -36209,9 +36229,13 @@ export type PostChineseAstrologyCalendarAuspiciousDaysResponses = {
                  */
                 planet: string;
                 /**
-                 * Animal emblem of the mansion, the third character of its full Chinese name.
+                 * Animal emblem of the mansion, the third character of its full Chinese name. English and canonical, identical in every language, matching how clashAnimal behaves on the same response. The translation is in animalLocalized.
                  */
                 animal: string;
+                /**
+                 * Animal emblem in the requested language. Absent when lang is en, and absent when a language has no entry, so a caller falls back to animal.
+                 */
+                animalLocalized?: string;
             };
             /**
              * The zodiac animal the day clashes with, which is the animal six branches away from the day branch. Anyone born in that animal year traditionally avoids the day for anything important.
@@ -37442,7 +37466,7 @@ export type PostFengShuiFlyingStarsNatalResponses = {
              */
             id: string;
             /**
-             * Display name of the structure. Always English, whatever the lang parameter says.
+             * Display name of the structure, TRANSLATED IN PLACE under the lang parameter. Switch on structure.id, which is the stable machine value in every language. Unlike the star and formation names beside it, this field has no nameLocalized sibling.
              */
             name: string;
             /**
@@ -38235,7 +38259,11 @@ export type GetFengShuiAfflictionsByYearResponses = {
          */
         taiSui: {
             /**
-             * Display name of the affliction. Always English, whatever the lang parameter says, so it stays safe to compare against in code.
+             * Stable machine key for the affliction: taiSui, suiPo, sanSha or fiveYellow. Always English, identical in every language, and the field to branch on. Use this rather than name, which is display copy and does translate.
+             */
+            id: string;
+            /**
+             * Display name of the affliction, translated in place when lang is set (Tai Sui in English, 太岁 under zh-Hans). Display copy, never a comparison key: branch on id instead.
              */
             name: string;
             /**
@@ -38306,7 +38334,11 @@ export type GetFengShuiAfflictionsByYearResponses = {
          */
         suiPo: {
             /**
-             * Display name of the affliction. Always English, whatever the lang parameter says, so it stays safe to compare against in code.
+             * Stable machine key for the affliction: taiSui, suiPo, sanSha or fiveYellow. Always English, identical in every language, and the field to branch on. Use this rather than name, which is display copy and does translate.
+             */
+            id: string;
+            /**
+             * Display name of the affliction, translated in place when lang is set (Tai Sui in English, 太岁 under zh-Hans). Display copy, never a comparison key: branch on id instead.
              */
             name: string;
             /**
@@ -38369,7 +38401,11 @@ export type GetFengShuiAfflictionsByYearResponses = {
          */
         sanSha: {
             /**
-             * Display name of the affliction. Always English, whatever the lang parameter says, so it stays safe to compare against in code.
+             * Stable machine key for the affliction: taiSui, suiPo, sanSha or fiveYellow. Always English, identical in every language, and the field to branch on. Use this rather than name, which is display copy and does translate.
+             */
+            id: string;
+            /**
+             * Display name of the affliction, translated in place when lang is set (Tai Sui in English, 太岁 under zh-Hans). Display copy, never a comparison key: branch on id instead.
              */
             name: string;
             /**
@@ -38413,7 +38449,7 @@ export type GetFengShuiAfflictionsByYearResponses = {
                  */
                 id: string;
                 /**
-                 * Display name of the part. Always English, whatever the lang parameter says.
+                 * Display name of the part, translated in place when lang is set. Display copy, never a comparison key: branch on id instead.
                  */
                 name: string;
                 /**
@@ -38473,7 +38509,11 @@ export type GetFengShuiAfflictionsByYearResponses = {
          */
         fiveYellow: {
             /**
-             * Display name of the affliction. Always English, whatever the lang parameter says, so it stays safe to compare against in code.
+             * Stable machine key for the affliction: taiSui, suiPo, sanSha or fiveYellow. Always English, identical in every language, and the field to branch on. Use this rather than name, which is display copy and does translate.
+             */
+            id: string;
+            /**
+             * Display name of the affliction, translated in place when lang is set (Tai Sui in English, 太岁 under zh-Hans). Display copy, never a comparison key: branch on id instead.
              */
             name: string;
             /**