@roxyapi/sdk 1.2.10 → 1.2.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/AGENTS.md +152 -70
  2. package/README.md +165 -42
  3. package/dist/factory.cjs +1 -1
  4. package/dist/factory.js +1 -1
  5. package/dist/version.d.ts +1 -1
  6. package/docs/llms-full.txt +51 -0
  7. package/package.json +2 -1
  8. package/src/version.ts +1 -1
package/AGENTS.md CHANGED
@@ -1,6 +1,6 @@
1
- # @roxyapi/sdk — Agent Guide
1
+ # @roxyapi/sdk - Agent Guide
2
2
 
3
- TypeScript SDK for RoxyAPI. Multi-domain spiritual and metaphysical intelligence API. One API key, fully typed, zero runtime dependencies.
3
+ TypeScript SDK for RoxyAPI. Eleven domains (Western astrology, Vedic astrology, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers, location, usage). One API key, fully typed, zero runtime dependencies.
4
4
 
5
5
  > Before writing any code with this SDK, read `docs/llms-full.txt` in this package for the complete method reference with examples.
6
6
 
@@ -18,74 +18,93 @@ const roxy = createRoxy(process.env.ROXY_API_KEY!);
18
18
 
19
19
  `createRoxy` sets the base URL (`https://roxyapi.com/api/v2`) and auth header automatically. Every method returns `{ data, error, response }`.
20
20
 
21
+ ## Critical rule: geocode before any chart endpoint
22
+
23
+ Every chart, horoscope, panchang, dasha, dosha, navamsa, KP, synastry, compatibility, and natal endpoint needs `latitude`, `longitude`, and (for Western) `timezone`. **Never ask the user for coordinates.** Always call `roxy.location.searchCities` first.
24
+
25
+ ```typescript
26
+ const { data: cities } = await roxy.location.searchCities({ query: { q: 'Mumbai' } });
27
+ const { latitude, longitude, timezone } = cities[0];
28
+ ```
29
+
21
30
  ## Domains
22
31
 
23
32
  Type `roxy.` to see all available namespaces. Type `roxy.{domain}.` to see every method in that domain.
24
33
 
25
- | Namespace | What it covers |
26
- |-----------|----------------|
27
- | `roxy.astrology` | Western astrology: natal charts, horoscopes, synastry, moon phases, transits, compatibility |
28
- | `roxy.vedicAstrology` | Vedic/Jyotish: birth charts, dashas, nakshatras, panchang, KP system, doshas, yogas |
29
- | `roxy.tarot` | Rider-Waite-Smith deck: spreads, daily pulls, yes/no, Celtic Cross, custom layouts |
30
- | `roxy.numerology` | Life path, expression, soul urge, personal year, karmic analysis, compatibility |
31
- | `roxy.crystals` | Crystal healing properties, zodiac/chakra pairings, birthstones, search |
32
- | `roxy.iching` | I Ching: hexagrams, trigrams, coin casting, daily readings |
33
- | `roxy.angelNumbers` | Angel number meanings, pattern analysis, daily guidance |
34
- | `roxy.dreams` | Dream symbol dictionary and interpretations |
35
- | `roxy.location` | City geocoding for birth chart coordinates |
36
- | `roxy.usage` | API usage stats and subscription info |
34
+ <!-- BEGIN:DOMAINS -->
35
+ | Namespace | Endpoints | What it covers |
36
+ |-----------|-----------|----------------|
37
+ | `roxy.astrology` | 22 | Western astrology: natal charts, horoscopes, synastry, moon phases, transits, compatibility |
38
+ | `roxy.vedicAstrology` | 42 | Vedic/Jyotish: birth charts, dashas, nakshatras, panchang, KP system, doshas, yogas |
39
+ | `roxy.tarot` | 10 | Rider-Waite-Smith deck: spreads, daily pulls, yes/no, Celtic Cross, custom layouts |
40
+ | `roxy.numerology` | 16 | Life path, expression, soul urge, personal year, karmic analysis, compatibility |
41
+ | `roxy.dreams` | 5 | Dream symbol dictionary and interpretations |
42
+ | `roxy.angelNumbers` | 4 | Angel number meanings, pattern analysis, daily guidance |
43
+ | `roxy.iching` | 9 | I Ching: hexagrams, trigrams, coin casting, daily readings |
44
+ | `roxy.crystals` | 12 | Crystal healing properties, zodiac/chakra pairings, birthstones, search |
45
+ | `roxy.biorhythm` | 6 | 10-cycle biorhythm readings, forecasts, critical days, compatibility, daily check-ins (wellness, dating, productivity) |
46
+ | `roxy.location` | 3 | City geocoding for birth chart coordinates |
47
+ | `roxy.usage` | 1 | API usage stats and subscription info |
48
+ <!-- END:DOMAINS -->
49
+
50
+ **Total:** 130 endpoints across 10 product domains plus usage. Counts auto-sync from `specs/openapi.json` at release time.
37
51
 
38
52
  ## Critical patterns
39
53
 
40
- ### GET endpoints — use `path` for URL parameters
54
+ ### Two-step pattern for coordinate-dependent endpoints
41
55
 
42
56
  ```typescript
43
- const { data } = await roxy.astrology.getDailyHoroscope({
44
- path: { sign: 'aries' },
45
- });
57
+ const { data: cities } = await roxy.location.searchCities({ query: { q: 'Delhi' } });
58
+ const { latitude, longitude, timezone } = cities[0];
46
59
 
47
- const { data } = await roxy.crystals.getCrystal({
48
- path: { slug: 'amethyst' },
60
+ const { data: chart } = await roxy.astrology.generateNatalChart({
61
+ body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone },
49
62
  });
50
63
  ```
51
64
 
52
- ### POST endpoints — use `body` for request data
65
+ ### GET endpoints - use `path` for URL params, `query` for query params
66
+
67
+ ```typescript
68
+ await roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } });
69
+ await roxy.crystals.getCrystalsByZodiac({ path: { sign: 'leo' } });
70
+ await roxy.crystals.searchCrystals({ query: { q: 'amethyst' } });
71
+ ```
72
+
73
+ ### POST endpoints - use `body` for request data
53
74
 
54
75
  Most valuable endpoints (charts, spreads, calculations) are POST:
55
76
 
56
77
  ```typescript
57
- // Birth chart — requires date, time, coordinates
58
- const { data } = await roxy.astrology.generateNatalChart({
59
- body: {
60
- date: '1990-01-15',
61
- time: '14:30:00',
62
- latitude: 28.6139,
63
- longitude: 77.209,
64
- },
78
+ await roxy.astrology.generateNatalChart({
79
+ body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone },
65
80
  });
66
81
 
67
- // Tarot spread
68
- const { data } = await roxy.tarot.castCelticCross({
69
- body: { question: 'What should I focus on?' },
82
+ await roxy.vedicAstrology.generateBirthChart({
83
+ body: { date: '1990-01-15', time: '14:30:00', latitude, longitude },
70
84
  });
71
85
 
72
- // Numerology
73
- const { data } = await roxy.numerology.calculateLifePath({
74
- body: { year: 1990, month: 1, day: 15 },
75
- });
86
+ await roxy.tarot.castCelticCross({ body: { question: 'What should I focus on?' } });
87
+
88
+ await roxy.numerology.calculateLifePath({ body: { year: 1990, month: 1, day: 15 } });
76
89
  ```
77
90
 
78
- ### Query parameters
91
+ ### Multi-language via `query: { lang }`
92
+
93
+ Eight languages: `en`, `tr`, `de`, `es`, `fr`, `hi`, `pt`, `ru`. Defaults to `en`.
79
94
 
80
95
  ```typescript
81
- const { data } = await roxy.crystals.searchCrystals({
82
- query: { q: 'amethyst' },
96
+ await roxy.tarot.getDailyCard({ body: { date: '2026-04-22' }, query: { lang: 'es' } });
97
+ await roxy.numerology.calculateLifePath({
98
+ body: { year: 1990, month: 1, day: 15 },
99
+ query: { lang: 'hi' },
83
100
  });
84
101
  ```
85
102
 
103
+ Supported: `astrology`, `vedicAstrology`, `numerology`, `tarot`, `biorhythm`, `iching`, `crystals`, `angelNumbers`. English-only: `dreams`, `location`, `usage`.
104
+
86
105
  ### Error handling
87
106
 
88
- All errors return `{ error: string, code: string }`. The `error` field is human-readable (may change wording). The `code` field is machine-readable (stable, safe to switch on).
107
+ All errors return `{ error: string, code: string }`. The `error` field is human-readable (may change wording). The `code` field is machine-readable (stable, switch on this).
89
108
 
90
109
  ```typescript
91
110
  const { data, error, response } = await roxy.astrology.getDailyHoroscope({
@@ -93,16 +112,12 @@ const { data, error, response } = await roxy.astrology.getDailyHoroscope({
93
112
  });
94
113
 
95
114
  if (error) {
96
- // error is { error: string, code: string } on 4xx/5xx
97
115
  console.error('Code:', error.code, 'Message:', error.error);
98
116
  return;
99
117
  }
100
- // data is fully typed after error check
101
118
  console.log(data.sign, data.overview);
102
119
  ```
103
120
 
104
- Error codes:
105
-
106
121
  | Status | Code | When |
107
122
  |--------|------|------|
108
123
  | 400 | `validation_error` | Missing or invalid parameters |
@@ -116,46 +131,112 @@ Error codes:
116
131
 
117
132
  ## Common tasks
118
133
 
134
+ Ordered by domain priority (Western, Vedic, Numerology, Tarot, Biorhythm, I Ching, Crystals, Dreams, Angel Numbers, Location, Usage).
135
+
119
136
  | Task | Code |
120
137
  |------|------|
121
138
  | Daily horoscope | `roxy.astrology.getDailyHoroscope({ path: { sign } })` |
122
- | Birth chart (Western) | `roxy.astrology.generateNatalChart({ body: { date, time, latitude, longitude } })` |
123
- | Birth chart (Vedic) | `roxy.vedicAstrology.generateBirthChart({ body: { date, time, latitude, longitude } })` |
139
+ | Natal chart (Western) | `roxy.astrology.generateNatalChart({ body: { date, time, latitude, longitude, timezone } })` |
140
+ | Synastry | `roxy.astrology.calculateSynastry({ body: { person1, person2 } })` |
124
141
  | Compatibility score | `roxy.astrology.calculateCompatibility({ body: { person1, person2 } })` |
125
- | Tarot daily card | `roxy.tarot.getDailyCard({ body: { date } })` |
126
- | Celtic Cross reading | `roxy.tarot.castCelticCross({ body: { question } })` |
127
- | Life Path number | `roxy.numerology.calculateLifePath({ body: { year, month, day } })` |
128
- | Full numerology chart | `roxy.numerology.generateNumerologyChart({ body: { date, name } })` |
142
+ | Current moon phase | `roxy.astrology.getCurrentMoonPhase()` |
143
+ | Transits | `roxy.astrology.calculateTransits({ body: { natalChart } })` |
144
+ | Kundli (Vedic birth chart) | `roxy.vedicAstrology.generateBirthChart({ body: { date, time, latitude, longitude } })` |
145
+ | Panchang (detailed) | `roxy.vedicAstrology.getDetailedPanchang({ body: { date, latitude, longitude } })` |
146
+ | Choghadiya | `roxy.vedicAstrology.getChoghadiya({ body: { date, latitude, longitude } })` |
147
+ | Current dasha | `roxy.vedicAstrology.getCurrentDasha({ body: { date, time, latitude, longitude } })` |
148
+ | Mangal Dosha | `roxy.vedicAstrology.checkManglikDosha({ body: { date, time, latitude, longitude } })` |
149
+ | Guna Milan (matching) | `roxy.vedicAstrology.calculateGunMilan({ body: { person1, person2 } })` |
150
+ | Navamsa (D9) | `roxy.vedicAstrology.generateNavamsa({ body: { date, time, latitude, longitude } })` |
151
+ | KP chart | `roxy.vedicAstrology.generateKpChart({ body: { date, time, latitude, longitude } })` |
152
+ | Nakshatra detail | `roxy.vedicAstrology.getNakshatra({ path: { id: 'ashwini' } })` |
153
+ | Life path number | `roxy.numerology.calculateLifePath({ body: { year, month, day } })` |
154
+ | Full numerology chart | `roxy.numerology.generateNumerologyChart({ body: { fullName, year, month, day } })` |
155
+ | Personal year | `roxy.numerology.calculatePersonalYear({ body: { month, day } })` |
156
+ | Daily tarot card | `roxy.tarot.getDailyCard({ body: { seed } })` |
157
+ | Three-card spread | `roxy.tarot.castThreeCard({ body: { question } })` |
158
+ | Celtic Cross | `roxy.tarot.castCelticCross({ body: { question } })` |
159
+ | Yes / no tarot | `roxy.tarot.castYesNo({ body: { question } })` |
160
+ | Daily biorhythm | `roxy.biorhythm.getDailyBiorhythm({ body: { seed } })` |
161
+ | Biorhythm forecast | `roxy.biorhythm.getForecast({ body: { birthDate } })` |
162
+ | Biorhythm compatibility | `roxy.biorhythm.calculateBioCompatibility({ body: { person1, person2 } })` |
163
+ | Daily hexagram | `roxy.iching.getDailyHexagram({ body: { seed } })` |
164
+ | Cast I Ching reading | `roxy.iching.castReading()` |
165
+ | Hexagram detail | `roxy.iching.getHexagram({ path: { number: 1 } })` |
129
166
  | Crystal by zodiac | `roxy.crystals.getCrystalsByZodiac({ path: { sign } })` |
130
- | I Ching reading | `roxy.iching.castReading()` |
131
- | Angel number meaning | `roxy.angelNumbers.getAngelNumber({ path: { number: '1111' } })` |
167
+ | Crystal by chakra | `roxy.crystals.getCrystalsByChakra({ path: { chakra } })` |
132
168
  | Dream symbol lookup | `roxy.dreams.getDreamSymbol({ path: { id: 'flying' } })` |
169
+ | Angel number meaning | `roxy.angelNumbers.getAngelNumber({ path: { number: '1111' } })` |
170
+ | Universal number lookup | `roxy.angelNumbers.analyzeNumberSequence({ query: { number: '1234' } })` |
133
171
  | Find city coordinates | `roxy.location.searchCities({ query: { q: 'Mumbai' } })` |
134
172
  | Check API usage | `roxy.usage.getUsageStats()` |
135
173
 
136
- ## Location helper
137
-
138
- Most chart endpoints need `latitude` and `longitude`. Use the location API to geocode:
139
-
140
- ```typescript
141
- const { data: cities } = await roxy.location.searchCities({
142
- query: { q: 'Mumbai, India' },
143
- });
144
- const city = cities[0];
145
- // Use city.latitude and city.longitude in chart requests
146
- ```
174
+ ## Field formats that trip agents
175
+
176
+ These are the fields AI agents most often get wrong. Copy the format column exactly.
177
+
178
+ | Field | Format | Good | Bad |
179
+ |-------|--------|------|-----|
180
+ | `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"` |
181
+ | `date` | ISO date string | `"1990-01-15"` | `"Jan 15 1990"`, `new Date()`, `"15/01/1990"`, `"1990-1-15"` |
182
+ | `time` | 24-hour string | `"14:30:00"`, `"09:00:00"` | `"2:30 PM"`, `"14:30"` (no seconds), `"9:0:0"` (no leading zeros) |
183
+ | `latitude` | Decimal degrees (number) | `28.6139` (Delhi), `-33.8688` (Sydney), `40.7128` (NYC) | `"28°36'N"`, `"28 36 50"`, strings |
184
+ | `longitude` | Decimal degrees (number) | `77.209` (Delhi), `-74.006` (NYC), `139.6917` (Tokyo) | Same as latitude - no DMS strings |
185
+ | `sign` (horoscope path) | Lowercase zodiac name | `aries`, `taurus`, `gemini`, ... `pisces` | `"Aries"`, `"♈"`, `"1"`, `"ARIES"` (case-insensitive but prefer lowercase) |
186
+ | `fullName` (numerology) | Birth-certificate name | `"John William Smith"`, `"Priya Rajesh Sharma"` | Nickname, married name, partial name - affects all letter-based calcs |
187
+ | `seed` | Any string (deterministic) | `"user-42"`, `"session-abc-123"`, email hash | Numbers, objects - must be string |
188
+ | `number` (angel numbers path) | String | `"1111"`, `"777"`, `"1234"` | `1111` (int) fails path validation |
189
+ | `id` (nakshatra / dream / tarot) | Slug | `"ashwini"`, `"flying"`, `"the-fool"`, `"three-of-cups"` | Display names, uppercase, spaces |
190
+ | `houseSystem` | Enum | `"placidus"` (default), `"whole-sign"`, `"equal"`, `"koch"` | `"Placidus"`, `"whole_sign"`, `"WS"` |
191
+ | `ayanamsa` (KP) | Enum | `"kp-newcomb"` (default), `"kp-old"`, `"lahiri"`, `"custom"` | `"KP"`, `"New Comb"`, `"Lahiri"` |
192
+ | `nodeType` | Enum | `"true-node"`, `"mean-node"` | `"true"`, `"mean"`, `"True Node"` |
193
+ | `count` (tarot draw) | Integer 1 to 78 | `3`, `10`, `78` | `0`, `79`, strings, floats |
194
+ | `mahadasha` (path) | Planet name | `"Ketu"`, `"Venus"`, `"Sun"`, `"Moon"`, `"Mars"`, `"Rahu"`, `"Jupiter"`, `"Saturn"`, `"Mercury"` | `"KETU"` (works, case-insensitive), `"ke"`, `"Ke-tu"` |
195
+ | `person1` / `person2` | Object with full birth data | `{ date, time, latitude, longitude, timezone }` (Western) or `{ date, time, latitude, longitude }` (Vedic) | Separate top-level fields, missing time, partial object |
196
+ | `question` (tarot / iching) | Optional string | `"Should I accept the job offer?"`, `"What should I focus on this week?"` | Leave undefined for general reading. More specific = better interpretation. |
197
+ | `year` / `month` / `day` (numerology) | Integer | `1990`, `1`, `15` | Zero-padded strings `"01"`, decimals, full dates |
198
+
199
+ ### Timezone cheat sheet (most-asked locations)
200
+
201
+ | Region | Decimal | Region | Decimal |
202
+ |--------|---------|--------|---------|
203
+ | UTC / London (winter) | `0` | Dubai | `4` |
204
+ | London (summer, BST) | `1` | Karachi | `5` |
205
+ | Berlin / Paris | `1` (winter) / `2` (summer) | Delhi / Mumbai (IST) | `5.5` |
206
+ | Istanbul | `3` | Kathmandu (NPT) | `5.75` |
207
+ | Moscow | `3` | Dhaka | `6` |
208
+ | Tehran | `3.5` (winter) / `4.5` (summer) | Bangkok | `7` |
209
+ | Adelaide | `9.5` (winter) / `10.5` (summer) | Singapore / Beijing | `8` |
210
+ | New York (EST / EDT) | `-5` / `-4` | Tokyo | `9` |
211
+ | Chicago (CST / CDT) | `-6` / `-5` | Sydney | `10` (winter) / `11` (summer) |
212
+ | Denver (MST / MDT) | `-7` / `-6` | Auckland | `12` (winter) / `13` (summer) |
213
+ | Los Angeles (PST / PDT) | `-8` / `-7` | Honolulu | `-10` |
214
+
215
+ 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.
216
+
217
+ ## MCP equivalents
218
+
219
+ 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:
220
+
221
+ - `POST /astrology/natal-chart` -> `post_astrology_natal_chart` on `/mcp/astrology`
222
+ - `GET /astrology/horoscope/{sign}/daily` -> `get_astrology_horoscope_sign_daily` on `/mcp/astrology`
223
+ - `POST /vedic-astrology/birth-chart` -> `post_vedic_astrology_birth_chart` on `/mcp/vedic-astrology`
224
+ - `POST /tarot/spreads/celtic-cross` -> `post_tarot_spreads_celtic_cross` on `/mcp/tarot`
225
+
226
+ Use the SDK for typed TypeScript apps. Use MCP for AI agents (Claude Desktop, Cursor MCP, OpenAI agents) where the agent selects tools based on user intent.
147
227
 
148
228
  ## Gotchas
149
229
 
150
- - **Parameters are objects, not positional.** Always `{ path: {...} }`, `{ body: {...} }`, or `{ query: {...} }` — never positional arguments.
151
- - **Do not guess method names.** Type `roxy.domain.` and let autocomplete show available methods. Method names come from `operationId` in the OpenAPI spec, not URL paths.
152
- - **Do not use raw `fetch`.** The SDK handles auth headers, base URL, and typed responses.
230
+ - **Geocode first.** Any chart, panchang, synastry, compatibility, or natal endpoint needs coordinates. Call `roxy.location.searchCities` before the chart method.
231
+ - **Parameters are objects, not positional.** Always `{ path: {...} }`, `{ body: {...} }`, or `{ query: {...} }`.
232
+ - **Do not guess method names.** Type `roxy.domain.` and let autocomplete show them. Method names come from `operationId` in the OpenAPI spec, not URL paths.
233
+ - **Do not use raw `fetch`.** The SDK handles auth, base URL, and typed responses.
153
234
  - **Do not expose API keys client-side.** Call Roxy from server code, API routes, or server components only.
154
- - **Chart endpoints need coordinates.** Use `roxy.location.searchCities()` to get latitude/longitude before calling any birth chart or panchang method.
155
- - **Date format is `YYYY-MM-DD`, time is `HH:MM:SS`.** Both are strings. Timezone is optional (IANA format like `America/New_York`).
156
- - **All list endpoints may return paginated objects** (e.g. `{ items: [...], total: N }`) rather than raw arrays. Check the type.
235
+ - **Date format is `YYYY-MM-DD`, time is `HH:MM:SS`.** Both are strings.
236
+ - **Western `timezone` is required** (decimal hours, `-5` for EST, `5.5` for IST, `0` for UTC). Vedic endpoints accept an optional `timezone` that defaults to `5.5` (IST).
157
237
  - **`data` and `error` are mutually exclusive.** If `error` is set, `data` is `undefined` and vice versa.
158
- - **Errors have `error` (message) and `code` (machine-readable).** Switch on `code`, not `error` — the message may change wording.
238
+ - **Switch on `error.code`, not `error.error`.** The message may change; the code is stable.
239
+ - **List endpoints may return paginated objects** (`{ items, total }`) instead of raw arrays. Check the type.
159
240
 
160
241
  ## Links
161
242
 
@@ -163,3 +244,4 @@ const city = cities[0];
163
244
  - Interactive API docs: https://roxyapi.com/api-reference
164
245
  - Pricing and API keys: https://roxyapi.com/pricing
165
246
  - MCP for AI agents: https://roxyapi.com/docs/mcp
247
+ - Python SDK: https://pypi.org/project/roxy-sdk/
package/README.md CHANGED
@@ -5,9 +5,9 @@
5
5
  [![API Reference](https://img.shields.io/badge/api%20reference-roxyapi.com-blue)](https://roxyapi.com/api-reference)
6
6
  [![Pricing](https://img.shields.io/badge/pricing-roxyapi.com-blue)](https://roxyapi.com/pricing)
7
7
 
8
- TypeScript SDK for [RoxyAPI](https://roxyapi.com). Multiple domains, fully typed endpoints, one API key.
8
+ TypeScript SDK for [RoxyAPI](https://roxyapi.com). Natal charts, Vedic kundli, numerology, tarot, biorhythm, I Ching, crystals, dreams, and angel numbers. Eleven domains, one API key, fully typed.
9
9
 
10
- Build astrology apps, tarot platforms, birth chart generators, and compatibility tools without writing a single calculation.
10
+ Build astrology apps, kundli matching, tarot platforms, compatibility tools, and daily-horoscope features without writing a single calculation.
11
11
 
12
12
  ## Install
13
13
 
@@ -24,57 +24,155 @@ import { createRoxy } from '@roxyapi/sdk';
24
24
 
25
25
  const roxy = createRoxy(process.env.ROXY_API_KEY!);
26
26
 
27
- // Daily horoscope
27
+ // Step 1: geocode the birth city (required for any chart endpoint)
28
+ const { data: cities } = await roxy.location.searchCities({
29
+ query: { q: 'Mumbai, India' },
30
+ });
31
+ const { latitude, longitude, timezone } = cities[0];
32
+
33
+ // Step 2: Western natal chart
34
+ const { data: chart } = await roxy.astrology.generateNatalChart({
35
+ body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone },
36
+ });
37
+
38
+ // Vedic kundli uses the same inputs
39
+ const { data: kundli } = await roxy.vedicAstrology.generateBirthChart({
40
+ body: { date: '1990-01-15', time: '14:30:00', latitude, longitude },
41
+ });
42
+ ```
43
+
44
+ `createRoxy` sets the base URL (`https://roxyapi.com/api/v2`) and injects the auth header and SDK identification header on every request.
45
+
46
+ ## Location first
47
+
48
+ Every chart, horoscope, panchang, dasha, dosha, navamsa, KP, synastry, compatibility, and natal endpoint needs `latitude`, `longitude`, and (for Western) `timezone`. **Never ask users to type coordinates.** Call `roxy.location.searchCities({ query: { q: city } })` first, then feed the result into the chart method.
49
+
50
+ ```typescript
51
+ const { data } = await roxy.location.searchCities({ query: { q: 'Tokyo' } });
52
+ const { latitude, longitude, timezone } = data[0];
53
+ ```
54
+
55
+ ## Domains
56
+
57
+ <!-- BEGIN:DOMAINS -->
58
+ | Namespace | Endpoints | What it covers |
59
+ |-----------|-----------|----------------|
60
+ | `roxy.astrology` | 22 | Western astrology: natal charts, horoscopes, synastry, moon phases |
61
+ | `roxy.vedicAstrology` | 42 | Vedic/Jyotish: birth charts, dashas, nakshatras, panchang, KP system |
62
+ | `roxy.tarot` | 10 | 78-card readings: spreads, daily pulls, yes/no, Celtic Cross |
63
+ | `roxy.numerology` | 16 | Life path, expression, soul urge, personal year, karmic lessons |
64
+ | `roxy.dreams` | 5 | Dream symbol dictionary: 3,000+ interpretations |
65
+ | `roxy.angelNumbers` | 4 | Angel number lookup, pattern analysis, daily guidance |
66
+ | `roxy.iching` | 9 | I Ching hexagrams, trigrams, daily readings |
67
+ | `roxy.crystals` | 12 | Crystal meanings, healing properties, zodiac and chakra pairings |
68
+ | `roxy.biorhythm` | 6 | 10-cycle biorhythm readings, forecasts, critical days, compatibility |
69
+ | `roxy.location` | 3 | City and country search for birth chart coordinates |
70
+ | `roxy.usage` | 1 | API usage stats, rate limits, subscription info |
71
+ <!-- END:DOMAINS -->
72
+
73
+ ## Recipes
74
+
75
+ ### Daily horoscope (wellness, news, lifestyle apps)
76
+
77
+ ```typescript
28
78
  const { data } = await roxy.astrology.getDailyHoroscope({
29
79
  path: { sign: 'aries' },
30
80
  });
81
+ // data.overview, data.love, data.career, data.luckyNumber, ...
82
+ ```
83
+
84
+ ### Vedic kundli (India market, matrimonial, muhurat)
31
85
 
32
- // Vedic birth chart
33
- const { data: chart } = await roxy.vedicAstrology.generateBirthChart({
34
- body: {
35
- date: '1990-01-15',
36
- time: '14:30:00',
37
- latitude: 28.6139,
38
- longitude: 77.209,
39
- },
86
+ ```typescript
87
+ const { data: cities } = await roxy.location.searchCities({ query: { q: 'Delhi' } });
88
+ const { latitude, longitude } = cities[0];
89
+
90
+ const { data: kundli } = await roxy.vedicAstrology.generateBirthChart({
91
+ body: { date: '1990-01-15', time: '14:30:00', latitude, longitude },
92
+ });
93
+ ```
94
+
95
+ ### Panchang (daily almanac, ritual planner)
96
+
97
+ ```typescript
98
+ const { data } = await roxy.vedicAstrology.getDetailedPanchang({
99
+ body: { date: '2026-04-22', latitude: 28.6139, longitude: 77.209 },
40
100
  });
101
+ // data.tithi, data.nakshatra, data.rahuKaal, data.abhijitMuhurta, ...
102
+ ```
103
+
104
+ ### Guna Milan (matrimonial matching)
105
+
106
+ ```typescript
107
+ const person1 = { date: '1990-01-15', time: '14:30:00', latitude: 28.61, longitude: 77.20 };
108
+ const person2 = { date: '1992-07-22', time: '09:00:00', latitude: 19.07, longitude: 72.87 };
109
+
110
+ const { data } = await roxy.vedicAstrology.calculateGunMilan({
111
+ body: { person1, person2 },
112
+ });
113
+ // data.total, data.maxScore (36), data.isCompatible, data.breakdown[8]
114
+ ```
115
+
116
+ ### Numerology life path (numerology calculators)
41
117
 
42
- // Tarot Celtic Cross spread
43
- const { data: reading } = await roxy.tarot.castCelticCross({
118
+ ```typescript
119
+ const { data } = await roxy.numerology.calculateLifePath({
120
+ body: { year: 1990, month: 1, day: 15 },
121
+ });
122
+ // data.number, data.type, data.hasKarmicDebt, data.meaning
123
+ ```
124
+
125
+ ### Tarot Celtic Cross (premium-tier tarot feature)
126
+
127
+ ```typescript
128
+ const { data } = await roxy.tarot.castCelticCross({
44
129
  body: { question: 'What should I focus on?' },
45
130
  });
131
+ // data.positions[10], data.reading
46
132
  ```
47
133
 
48
- `createRoxy` sets the base URL and injects SDK identification headers automatically. `auth` is required.
134
+ ### Daily biorhythm (wellness, productivity, sports apps)
49
135
 
50
- ## Domains
136
+ ```typescript
137
+ const { data } = await roxy.biorhythm.getDailyBiorhythm({
138
+ body: { seed: 'user-123' },
139
+ });
140
+ ```
141
+
142
+ ### I Ching cast (decision-making, meditation)
143
+
144
+ ```typescript
145
+ const { data } = await roxy.iching.castReading();
146
+ // data.hexagram, data.changingLinePositions, data.resultingHexagram
147
+ ```
148
+
149
+ ### Dream symbol lookup (journaling, self-discovery)
51
150
 
52
- | Namespace | What it covers |
53
- |-----------|----------------|
54
- | `roxy.angelNumbers` | Angel number lookup, pattern analysis, daily guidance |
55
- | `roxy.astrology` | Western astrology:natal charts, horoscopes, synastry, moon phases |
56
- | `roxy.vedicAstrology` | Vedic/Jyotish:birth charts, dashas, nakshatras, panchang, KP system |
57
- | `roxy.tarot` | 78-card readings:spreads, daily pulls, yes/no, Celtic Cross |
58
- | `roxy.numerology` | Life path, expression, soul urge, personal year, karmic lessons |
59
- | `roxy.iching` | I Ching hexagrams, trigrams, daily readings |
60
- | `roxy.crystals` | Crystal meanings, healing properties, zodiac and chakra pairings |
61
- | `roxy.dreams` | Dream symbol interpretations:3,000+ symbols |
62
- | `roxy.location` | City and country search for birth chart coordinates |
63
- | `roxy.usage` | API usage stats, rate limits, subscription info |
151
+ ```typescript
152
+ const { data } = await roxy.dreams.getDreamSymbol({ path: { id: 'flying' } });
153
+ ```
154
+
155
+ ### Angel number meaning (viral content, spiritual apps)
156
+
157
+ ```typescript
158
+ const { data } = await roxy.angelNumbers.getAngelNumber({
159
+ path: { number: '1111' },
160
+ });
161
+ ```
64
162
 
65
163
  ## Authentication
66
164
 
67
165
  Get your API key at [roxyapi.com/pricing](https://roxyapi.com/pricing). Instant delivery after checkout.
68
166
 
69
- Pass the key to `createRoxy`. Never expose your API key client-side. Call Roxy from your server or API routes.
70
-
71
167
  ```typescript
72
168
  import { createRoxy } from '@roxyapi/sdk';
73
169
 
74
170
  const roxy = createRoxy(process.env.ROXY_API_KEY!);
75
171
  ```
76
172
 
77
- For advanced use cases (custom fetch, interceptors, per-request auth), you can build the client manually:
173
+ Never expose your API key client-side. Call Roxy from your server or API routes only.
174
+
175
+ For advanced use (custom fetch, interceptors, per-request auth), build the client manually:
78
176
 
79
177
  ```typescript
80
178
  import { Roxy } from '@roxyapi/sdk';
@@ -89,36 +187,60 @@ const client = createClient(
89
187
  const roxy = new Roxy({ client });
90
188
  ```
91
189
 
190
+ ## Multi-language responses
191
+
192
+ 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:
193
+
194
+ ```typescript
195
+ const { data } = await roxy.tarot.getDailyCard({
196
+ body: { date: '2026-04-22' },
197
+ query: { lang: 'es' },
198
+ });
199
+ ```
200
+
201
+ Supported: `astrology`, `vedicAstrology`, `numerology`, `tarot`, `biorhythm`, `iching`, `crystals`, `angelNumbers`. English-only: `dreams`, `location`, `usage`. Untranslated fields fall back to English.
202
+
92
203
  ## Error handling
93
204
 
94
- Every method returns `{ data, error, response }`. Errors have `{ error: string, code: string }` — switch on `code` for programmatic handling.
205
+ Every method returns `{ data, error, response }`. On 4xx / 5xx the error shape is `{ error: string, code: string }`. Switch on `code` for programmatic handling.
95
206
 
96
207
  ```typescript
97
- const { data, error } = await roxy.astrology.getZodiacSign({
98
- path: { identifier: 'aries' },
208
+ const { data, error } = await roxy.astrology.getDailyHoroscope({
209
+ path: { sign: 'aries' },
99
210
  });
100
211
 
101
212
  if (error) {
102
- console.error(error.code, error.error); // e.g. "not_found", "Zodiac sign 'xyz' not found"
213
+ console.error(error.code, error.error);
103
214
  } else {
104
215
  console.log(data);
105
216
  }
106
217
  ```
107
218
 
219
+ | Status | Code | When |
220
+ |--------|------|------|
221
+ | 400 | `validation_error` | Missing or invalid parameters |
222
+ | 401 | `api_key_required` | No API key provided |
223
+ | 401 | `invalid_api_key` | Key format invalid or tampered |
224
+ | 401 | `subscription_not_found` | Key references non-existent subscription |
225
+ | 401 | `subscription_inactive` | Subscription cancelled, expired, or suspended |
226
+ | 404 | `not_found` | Resource not found |
227
+ | 429 | `rate_limit_exceeded` | Monthly quota reached |
228
+ | 500 | `internal_error` | Server error |
229
+
108
230
  ## TypeScript
109
231
 
110
- Every request and response is fully typed. IDE autocomplete shows available methods per domain and exact parameter shapes — no docs tab needed.
232
+ Every request and response is fully typed. IDE autocomplete shows available methods per domain and exact parameter shapes. No docs tab needed.
111
233
 
112
- ## AI agents (Cursor, Claude Code, Copilot, Codex)
234
+ ## AI agents (Cursor, Claude Code, Copilot, Codex, Gemini CLI)
113
235
 
114
- This package ships with bundled documentation that AI coding agents can read directly from `node_modules/`:
236
+ This package ships with bundled documentation that AI coding agents read directly from `node_modules/`:
115
237
 
116
- - **`AGENTS.md`** — Quick start, patterns, gotchas, and a common tasks reference table
117
- - **`docs/llms-full.txt`** — Complete method reference with code examples for every domain
238
+ - `AGENTS.md` - quick start, patterns, gotchas, common-tasks reference
239
+ - `docs/llms-full.txt` - complete method reference with code examples for every domain
118
240
 
119
- AI agents that support `AGENTS.md` (Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI) will read it automatically. For other tools, point your agent to `node_modules/@roxyapi/sdk/AGENTS.md`.
241
+ Agents supporting `AGENTS.md` (Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI) will pick it up automatically. For other tools, point your agent to `node_modules/@roxyapi/sdk/AGENTS.md`.
120
242
 
121
- Also available: [MCP server](https://roxyapi.com/docs/mcp) for AI agents that support the Model Context Protocol.
243
+ Also available: [remote MCP server](https://roxyapi.com/docs/mcp) per domain at `https://roxyapi.com/mcp/{domain}` (Streamable HTTP, no stdio / no self-hosting) for agents that speak the Model Context Protocol.
122
244
 
123
245
  ## Links
124
246
 
@@ -127,7 +249,8 @@ Also available: [MCP server](https://roxyapi.com/docs/mcp) for AI agents that su
127
249
  - [Pricing](https://roxyapi.com/pricing)
128
250
  - [MCP setup for AI agents](https://roxyapi.com/docs/mcp)
129
251
  - [Starter apps](https://roxyapi.com/starters)
130
- - [Issues](https://github.com/roxyapi/sdk-typescript/issues)
252
+ - [Python SDK](https://pypi.org/project/roxy-sdk/)
253
+ - [Issues](https://github.com/RoxyAPI/sdk-typescript/issues)
131
254
 
132
255
  ## License
133
256
 
package/dist/factory.cjs CHANGED
@@ -2821,7 +2821,7 @@ var Roxy = class _Roxy extends HeyApiClient {
2821
2821
  };
2822
2822
 
2823
2823
  // src/version.ts
2824
- var VERSION = "1.2.10";
2824
+ var VERSION = "1.2.12";
2825
2825
 
2826
2826
  // src/factory.ts
2827
2827
  function createRoxy(auth) {
package/dist/factory.js CHANGED
@@ -1986,7 +1986,7 @@ var Roxy = class _Roxy extends HeyApiClient {
1986
1986
  };
1987
1987
 
1988
1988
  // src/version.ts
1989
- var VERSION = "1.2.10";
1989
+ var VERSION = "1.2.12";
1990
1990
 
1991
1991
  // src/factory.ts
1992
1992
  function createRoxy(auth) {
package/dist/version.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- export declare const VERSION = "1.2.10";
1
+ export declare const VERSION = "1.2.12";
2
2
  //# sourceMappingURL=version.d.ts.map
package/docs/llms-full.txt CHANGED
@@ -9,6 +9,15 @@ import { createRoxy } from '@roxyapi/sdk';
9
9
  const roxy = createRoxy(process.env.ROXY_API_KEY!);
10
10
  ```
11
11
 
12
+ **Multi-language responses.** Interpretations are available in 8 languages: `en`, `tr`, `de`, `es`, `fr`, `hi`, `pt`, `ru`. Pass `query: { lang }` on any supported endpoint. Supported: astrology, vedicAstrology, tarot, numerology, crystals, iching, angelNumbers, biorhythm. English-only: dreams, location, usage. Languages without translations yet fall back to English.
13
+
14
+ ```typescript
15
+ const { data } = await roxy.astrology.getDailyHoroscope({
16
+ path: { sign: 'aries' },
17
+ query: { lang: 'es' },
18
+ });
19
+ ```
20
+
12
21
  ---
13
22
 
14
23
  ## Astrology (Western) — `roxy.astrology`
@@ -613,6 +622,48 @@ const { data } = await roxy.dreams.getDailyDreamSymbol({ body: { date: '2026-03-
613
622
 
614
623
  ---
615
624
 
625
+ ## Biorhythm — `roxy.biorhythm`
626
+
627
+ 10-cycle biorhythm calculations (physical, emotional, intellectual, intuitive, aesthetic, awareness, spiritual, passion, mastery, wisdom). All methods are POST. Only `birthDate` (`YYYY-MM-DD`) is required; dates default to today (UTC) when omitted. Every method accepts an optional `query: { lang }` (`en`, `tr`, `de`, `es`, `hi`, `pt`, `fr`, `ru`).
628
+
629
+ ```typescript
630
+ // Complete reading for a target date — all 10 cycles, phase detection, energy rating, interpretation, advice, critical day alerts
631
+ const { data } = await roxy.biorhythm.getReading({
632
+ body: { birthDate: '1990-01-15', targetDate: '2026-04-14' },
633
+ });
634
+
635
+ // Multi-day forecast (max 90-day range). Returns daily cycle values, energy ratings, critical days, best/worst day summary
636
+ const { data } = await roxy.biorhythm.getForecast({
637
+ body: { birthDate: '1990-01-15', startDate: '2026-04-14', endDate: '2026-05-14' },
638
+ });
639
+
640
+ // Critical days (zero crossings) in a range (max 180 days). Flags rare double and triple critical days
641
+ const { data } = await roxy.biorhythm.getCriticalDays({
642
+ body: { birthDate: '1990-01-15', startDate: '2026-04-14', endDate: '2026-07-14' },
643
+ });
644
+
645
+ // Compatibility between two people on a target date (per-cycle scores, overall rating, strengths, challenges, advice)
646
+ const { data } = await roxy.biorhythm.calculateBioCompatibility({
647
+ body: {
648
+ person1: { birthDate: '1990-01-15' },
649
+ person2: { birthDate: '1988-06-22' },
650
+ targetDate: '2026-04-14',
651
+ },
652
+ });
653
+
654
+ // Lightweight phase info for dashboards and widgets — no editorial text
655
+ const { data } = await roxy.biorhythm.getPhases({
656
+ body: { birthDate: '1990-01-15' },
657
+ });
658
+
659
+ // Daily check-in with seeded randomness — same seed + same date = same reading (perfect for push notifications)
660
+ const { data } = await roxy.biorhythm.getDailyBiorhythm({
661
+ body: { birthDate: '1990-01-15', seed: 'user-123' },
662
+ });
663
+ ```
664
+
665
+ ---
666
+
616
667
  ## Location — `roxy.location`
617
668
 
618
669
  Geocoding helper for birth chart coordinates.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@roxyapi/sdk",
3
- "version": "1.2.10",
3
+ "version": "1.2.12",
4
4
  "description": "TypeScript SDK for Roxy — the multi-domain spiritual intelligence API",
5
5
  "type": "module",
6
6
  "exports": {
@@ -26,6 +26,7 @@
26
26
  ],
27
27
  "scripts": {
28
28
  "generate": "bun run scripts/generate.ts",
29
+ "docs:sync": "bun run scripts/sync-docs.ts",
29
30
  "build": "tsup src/factory.ts src/client/index.ts --format esm,cjs && tsc -p tsconfig.build.json --emitDeclarationOnly",
30
31
  "typecheck": "tsc --noEmit",
31
32
  "test": "vitest run",
package/src/version.ts CHANGED
@@ -1 +1 @@
1
- export const VERSION = '1.2.10';
1
+ export const VERSION = '1.2.12';