@roxyapi/sdk 1.2.17 → 1.2.19

package/AGENTS.md

@@ -24,9 +24,12 @@ Every chart, horoscope, panchang, dasha, dosha, navamsa, KP, synastry, compatibi
 
 ```typescript
 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.
+const { latitude, longitude, timezone } = data.cities[0];
+// `timezone` is the IANA string ("Asia/Kolkata"). Pass it directly to any chart
+// endpoint and the server resolves it to the DST-correct decimal offset using
+// the chart's own `date`, so a January 1990 New York chart picks EST (-5) even
+// when you looked the city up in July. If you prefer numbers, `utcOffset`
+// (5.5, -5, 9, ...) also works and produces identical charts.
 ```
 
 ## Domains
@@ -228,7 +231,7 @@ LLMs hallucinate confidently in this category. These are the specific traps you
 - **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.
+- **Timezone affects Western calculations more than Vedic.** Western natal charts must respect DST at the time of birth. Vedic endpoints default to IST (`5.5`) which is DST-free. Pass the IANA `timezone` string from the Location API response (`"America/New_York"`, `"Asia/Kolkata"`) directly to chart calls and the server resolves the DST-correct offset for the chart `date`. Decimal `utcOffset` (5.5, -5, ...) also works and produces an identical chart.
 
 ## MCP equivalents
 
@@ -249,7 +252,7 @@ Use the SDK for typed TypeScript apps. Use MCP for AI agents (Claude Desktop, Cu
 - **Do not use raw `fetch`.** The SDK handles auth, base URL, and typed responses.
 - **Do not expose API keys client-side.** Call Roxy from server code, API routes, or server components only.
 - **Date format is `YYYY-MM-DD`, time is `HH:MM:SS`.** Both are strings.
-- **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).
+- **Western `timezone` is required** and accepts either a decimal (`-5` for EST, `5.5` for IST, `0` for UTC) or an IANA string (`"America/New_York"`, `"Asia/Kolkata"`, `"UTC"`). IANA is resolved to the DST-correct offset for the request `date`. Vedic endpoints accept an optional `timezone` that defaults to `5.5` (IST).
 - **`data` and `error` are mutually exclusive.** If `error` is set, `data` is `undefined` and vice versa.
 - **Switch on `error.code`, not `error.error`.** The message may change; the code is stable.
 - **List endpoints may return paginated objects** (`{ items, total }`) instead of raw arrays. Check the type.

package/README.md

@@ -5,9 +5,11 @@
 [![API Reference](https://img.shields.io/badge/api%20reference-roxyapi.com-blue)](https://roxyapi.com/api-reference)
 [![Pricing](https://img.shields.io/badge/pricing-roxyapi.com-blue)](https://roxyapi.com/pricing)
 
-The TypeScript SDK for [Roxy](https://roxyapi.com), the multi-domain spiritual intelligence API. One key, ten domains, fully typed. Western astrology API, Vedic astrology API, numerology API, tarot API, biorhythm API, I Ching API, crystals API, dream interpretation API, and angel numbers API behind a single subscription.
+TypeScript SDK for astrology, Vedic astrology, tarot, numerology, and more.
 
-Build a natal chart app, a kundli matching product, a daily horoscope feature, a tarot reading app, a numerology life path calculator, or a spiritual AI agent without writing a single calculation. Calculations are verified against NASA JPL Horizons; interpretations ship in eight languages.
+One API key. Fully typed. Verified against NASA JPL Horizons.
+
+The fastest way to add natal charts, kundli matching, daily horoscopes, tarot readings, and spiritual insights to Node.js apps, backends, and AI agents. Ten domains behind a single [Roxy](https://roxyapi.com) subscription, interpretations in eight languages.
 
 ## Install
 
@@ -17,6 +19,21 @@ npm install @roxyapi/sdk
 bun add @roxyapi/sdk
 ```
 
+## Start with one call
+
+Get real product value with a single typed call. No setup beyond your API key.
+
+```typescript
+import { createRoxy } from '@roxyapi/sdk';
+
+const roxy = createRoxy(process.env.ROXY_API_KEY!);
+
+const { data } = await roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } });
+console.log(data.overview, data.love, data.luckyNumber);
+```
+
+Then expand into charts, compatibility, tarot, numerology, and more.
+
 ## Quick start
 
 ```typescript
@@ -31,7 +48,7 @@ const { data } = await roxy.location.searchCities({
 const { latitude, longitude, timezone } = data.cities[0];
 
 // 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
+// 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 },
@@ -53,7 +70,7 @@ Every chart, horoscope, panchang, dasha, dosha, navamsa, KP, synastry, compatibi
 const { data } = await roxy.location.searchCities({ query: { q: 'Tokyo' } });
 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 endpoint and 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.
 ```
 
@@ -264,6 +281,22 @@ const { data: angel } = await roxy.angelNumbers.getAngelNumber({ path: { number:
 const { data: anyNumber } = await roxy.angelNumbers.analyzeNumberSequence({ query: { number: '4242' } });
 ```
 
+## Built for AI agents (Cursor, Claude Code, Copilot, Codex, Gemini CLI)
+
+This package ships with bundled documentation that AI coding agents read directly from `node_modules/`:
+
+- `AGENTS.md` for quick start, patterns, gotchas, common-tasks reference
+- `docs/llms-full.txt` for the complete method reference with examples per domain
+
+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`.
+
+Prefer MCP? Every domain has a [remote MCP server](https://roxyapi.com/docs/mcp) at `https://roxyapi.com/mcp/{domain}` (Streamable HTTP, no stdio, no self-hosting). One-line Claude Code setup:
+
+```bash
+claude mcp add-json --scope user roxy-astrology \
+  '{"type":"http","url":"https://roxyapi.com/mcp/astrology","headers":{"X-API-Key":"YOUR_KEY"}}'
+```
+
 ## Authentication
 
 Get your API key at [roxyapi.com/pricing](https://roxyapi.com/pricing). Instant delivery after checkout.
@@ -335,17 +368,6 @@ if (error) {
 
 Every request and response is fully typed. IDE autocomplete shows available methods per domain and exact parameter shapes. No docs tab needed.
 
-## AI agents (Cursor, Claude Code, Copilot, Codex, Gemini CLI)
-
-This package ships with bundled documentation that AI coding agents read directly from `node_modules/`:
-
-- `AGENTS.md` - quick start, patterns, gotchas, common-tasks reference
-- `docs/llms-full.txt` - complete method reference with code examples for every domain
-
-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`.
-
-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.
-
 ## Links
 
 - [Documentation](https://roxyapi.com/docs)

package/dist/factory.cjs

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

package/dist/factory.js

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

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.2.17";
+export declare const VERSION = "1.2.19";
 //# sourceMappingURL=version.d.ts.map

package/docs/llms-full.txt

@@ -22,7 +22,7 @@ const { data } = await roxy.astrology.getDailyHoroscope({
 
 ## Astrology (Western) — `roxy.astrology`
 
-Tropical zodiac, Placidus houses, NASA JPL DE405 validated positions.
+Tropical zodiac, Placidus houses, positions verified against NASA JPL Horizons.
 
 ### Horoscopes
 
@@ -671,13 +671,18 @@ Geocoding helper for birth chart coordinates.
 ```typescript
 // Search cities (autocomplete)
 const { data } = await roxy.location.searchCities({ query: { q: 'Mumbai' } });
-// Returns array: [{ name, country, latitude, longitude, timezone, ... }]
+// Returns envelope: { total, limit, offset, cities: [{ name, country, latitude, longitude, timezone, utcOffset, ... }, ...] }
+// `timezone` is the IANA string ("Asia/Kolkata"), `utcOffset` is the decimal fallback (5.5).
+// Pass `timezone` directly to any chart endpoint; the server resolves DST for the chart's `date`.
 
-// All 227 countries
-const { data } = await roxy.location.listCountries();
+const city = data.cities[0];
+const { latitude, longitude, timezone } = city;
+
+// All countries
+const { data: countries } = await roxy.location.listCountries();
 
 // Cities in a country
-const { data } = await roxy.location.getCitiesByCountry({ path: { iso2: 'IN' } });
+const { data: indianCities } = await roxy.location.getCitiesByCountry({ path: { iso2: 'IN' } });
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@roxyapi/sdk",
-	"version": "1.2.17",
+	"version": "1.2.19",
 	"description": "TypeScript SDK for Roxy — the multi-domain spiritual intelligence API",
 	"type": "module",
 	"exports": {
@@ -35,17 +35,27 @@
 	},
 	"keywords": [
 		"astrology",
+		"vedic",
 		"tarot",
 		"numerology",
-		"API",
-		"SDK",
-		"spiritual",
-		"roxy",
-		"vedic",
+		"horoscope",
+		"kundli",
+		"birth-chart",
+		"natal-chart",
 		"iching",
 		"crystals",
 		"angel-numbers",
-		"dreams"
+		"dreams",
+		"biorhythm",
+		"spiritual",
+		"API",
+		"SDK",
+		"typescript-sdk",
+		"nodejs",
+		"ai-agent",
+		"mcp",
+		"llm",
+		"roxy"
 	],
 	"license": "MIT",
 	"repository": {

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '1.2.17';
+export const VERSION = '1.2.19';