@roxyapi/sdk 1.0.1 → 1.1.0

package/AGENTS.md

@@ -0,0 +1,151 @@
+# @roxyapi/sdk — Agent Guide
+
+TypeScript SDK for RoxyAPI. Multi-domain spiritual and metaphysical intelligence API. 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.
+
+## Install and initialize
+
+```bash
+npm install @roxyapi/sdk
+```
+
+```typescript
+import { createRoxy } from '@roxyapi/sdk';
+
+const roxy = createRoxy(process.env.ROXY_API_KEY!);
+```
+
+`createRoxy` sets the base URL (`https://roxyapi.com/api/v2`) and auth header automatically. Every method returns `{ data, error, response }`.
+
+## Domains
+
+Type `roxy.` to see all available namespaces. Type `roxy.{domain}.` to see every method in that domain.
+
+| Namespace | What it covers |
+|-----------|----------------|
+| `roxy.astrology` | Western astrology: natal charts, horoscopes, synastry, moon phases, transits, compatibility |
+| `roxy.vedicAstrology` | Vedic/Jyotish: birth charts, dashas, nakshatras, panchang, KP system, doshas, yogas |
+| `roxy.tarot` | Rider-Waite-Smith deck: spreads, daily pulls, yes/no, Celtic Cross, custom layouts |
+| `roxy.numerology` | Life path, expression, soul urge, personal year, karmic analysis, compatibility |
+| `roxy.crystals` | Crystal healing properties, zodiac/chakra pairings, birthstones, search |
+| `roxy.iching` | I Ching: hexagrams, trigrams, coin casting, daily readings |
+| `roxy.angelNumbers` | Angel number meanings, pattern analysis, daily guidance |
+| `roxy.dreams` | Dream symbol dictionary and interpretations |
+| `roxy.location` | City geocoding for birth chart coordinates |
+| `roxy.usage` | API usage stats and subscription info |
+
+## Critical patterns
+
+### GET endpoints — use `path` for URL parameters
+
+```typescript
+const { data } = await roxy.astrology.getDailyHoroscope({
+  path: { sign: 'aries' },
+});
+
+const { data } = await roxy.crystals.getCrystal({
+  path: { slug: 'amethyst' },
+});
+```
+
+### POST endpoints — use `body` for request data
+
+Most valuable endpoints (charts, spreads, calculations) are POST:
+
+```typescript
+// Birth chart — requires date, time, coordinates
+const { data } = await roxy.astrology.generateNatalChart({
+  body: {
+    date: '1990-01-15',
+    time: '14:30:00',
+    latitude: 28.6139,
+    longitude: 77.209,
+  },
+});
+
+// Tarot spread
+const { data } = await roxy.tarot.castCelticCross({
+  body: { question: 'What should I focus on?' },
+});
+
+// Numerology
+const { data } = await roxy.numerology.calculateLifePath({
+  body: { year: 1990, month: 1, day: 15 },
+});
+```
+
+### Query parameters
+
+```typescript
+const { data } = await roxy.crystals.searchCrystals({
+  query: { q: 'amethyst' },
+});
+```
+
+### Error handling
+
+```typescript
+const { data, error, response } = await roxy.astrology.getDailyHoroscope({
+  path: { sign: 'aries' },
+});
+
+if (error) {
+  // error is { error: string } on 4xx/5xx
+  console.error('Status:', response?.status, 'Error:', error);
+  return;
+}
+// data is fully typed after error check
+console.log(data.sign, data.overview);
+```
+
+Common error codes: `401` invalid/missing API key, `403` subscription expired or limit reached, `429` rate limited, `404` resource not found.
+
+## Common tasks
+
+| Task | Code |
+|------|------|
+| Daily horoscope | `roxy.astrology.getDailyHoroscope({ path: { sign } })` |
+| Birth chart (Western) | `roxy.astrology.generateNatalChart({ body: { date, time, latitude, longitude } })` |
+| Birth chart (Vedic) | `roxy.vedicAstrology.generateBirthChart({ body: { date, time, latitude, longitude } })` |
+| Compatibility score | `roxy.astrology.calculateCompatibility({ body: { person1, person2 } })` |
+| Tarot daily card | `roxy.tarot.getDailyCard({ body: { date } })` |
+| Celtic Cross reading | `roxy.tarot.castCelticCross({ body: { question } })` |
+| Life Path number | `roxy.numerology.calculateLifePath({ body: { year, month, day } })` |
+| Full numerology chart | `roxy.numerology.generateNumerologyChart({ body: { date, name } })` |
+| Crystal by zodiac | `roxy.crystals.getCrystalsByZodiac({ path: { sign } })` |
+| I Ching reading | `roxy.iching.castReading()` |
+| Angel number meaning | `roxy.angelNumbers.getAngelNumber({ path: { number: '1111' } })` |
+| Dream symbol lookup | `roxy.dreams.getDreamSymbol({ path: { id: 'flying' } })` |
+| Find city coordinates | `roxy.location.searchCities({ query: { q: 'Mumbai' } })` |
+| Check API usage | `roxy.usage.getUsageStats()` |
+
+## Location helper
+
+Most chart endpoints need `latitude` and `longitude`. Use the location API to geocode:
+
+```typescript
+const { data: cities } = await roxy.location.searchCities({
+  query: { q: 'Mumbai, India' },
+});
+const city = cities[0];
+// Use city.latitude and city.longitude in chart requests
+```
+
+## Gotchas
+
+- **Parameters are objects, not positional.** Always `{ path: {...} }`, `{ body: {...} }`, or `{ query: {...} }` — never positional arguments.
+- **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.
+- **Do not use raw `fetch`.** The SDK handles auth headers, base URL, and typed responses.
+- **Do not expose API keys client-side.** Call Roxy from server code, API routes, or server components only.
+- **Chart endpoints need coordinates.** Use `roxy.location.searchCities()` to get latitude/longitude before calling any birth chart or panchang method.
+- **Date format is `YYYY-MM-DD`, time is `HH:MM:SS`.** Both are strings. Timezone is optional (IANA format like `America/New_York`).
+- **All list endpoints may return paginated objects** (e.g. `{ items: [...], total: N }`) rather than raw arrays. Check the type.
+- **`data` and `error` are mutually exclusive.** If `error` is set, `data` is `undefined` and vice versa.
+
+## Links
+
+- Full method reference: `docs/llms-full.txt` (bundled in this package)
+- Interactive API docs: https://roxyapi.com/api-reference
+- Pricing and API keys: https://roxyapi.com/pricing
+- MCP for AI agents: https://roxyapi.com/docs/mcp

package/README.md

@@ -5,7 +5,7 @@
 [![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)
 
-TypeScript SDK for [RoxyAPI](https://roxyapi.com). 8 domains, 120+ endpoints, one API key.
+TypeScript SDK for [RoxyAPI](https://roxyapi.com). Multiple domains, fully typed endpoints, one API key.
 
 Build astrology apps, tarot platforms, birth chart generators, and compatibility tools without writing a single calculation.
 
@@ -107,7 +107,18 @@ if (error) {
 
 ## TypeScript
 
-Every request and response is fully typed. IDE autocomplete shows available methods per domain and exact parameter shapes:no docs tab needed.
+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)
+
+This package ships with bundled documentation that AI coding agents can read directly from `node_modules/`:
+
+- **`AGENTS.md`** — Quick start, patterns, gotchas, and a common tasks reference table
+- **`docs/llms-full.txt`** — Complete method reference with code examples for every domain
+
+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`.
+
+Also available: [MCP server](https://roxyapi.com/docs/mcp) for AI agents that support the Model Context Protocol.
 
 ## Links
 

package/dist/factory.cjs

@@ -2673,8 +2673,8 @@ var Roxy = class _Roxy extends HeyApiClient {
   }
 };
 
-// package.json
-var version = "1.0.0";
+// src/version.ts
+var VERSION = "1.1.0";
 
 // src/factory.ts
 function createRoxy(auth) {
@@ -2683,7 +2683,7 @@ function createRoxy(auth) {
       baseUrl: "https://roxyapi.com/api/v2",
       auth,
       headers: {
-        "X-SDK-Client": `roxyapi-sdk-typescript/${version}`
+        "X-SDK-Client": `roxy-sdk-typescript/${VERSION}`
       }
     })
   );

package/dist/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,SAAS,CAAC;AAIxB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,KAAK,SAAS,GAAG,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;AAE3D;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAWhD"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,KAAK,SAAS,GAAG,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;AAE3D;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAWhD"}

package/dist/factory.js

@@ -1839,8 +1839,8 @@ var Roxy = class _Roxy extends HeyApiClient {
   }
 };
 
-// package.json
-var version = "1.0.0";
+// src/version.ts
+var VERSION = "1.1.0";
 
 // src/factory.ts
 function createRoxy(auth) {
@@ -1849,7 +1849,7 @@ function createRoxy(auth) {
       baseUrl: "https://roxyapi.com/api/v2",
       auth,
       headers: {
-        "X-SDK-Client": `roxyapi-sdk-typescript/${version}`
+        "X-SDK-Client": `roxy-sdk-typescript/${VERSION}`
       }
     })
   );

package/dist/version.d.ts

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

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC"}