@roxyapi/ui 0.3.0 → 0.4.0

package/AGENTS.md

@@ -1,6 +1,10 @@
 # AGENTS.md
 
-This file teaches AI coding agents (Claude Code, Cursor, Copilot, Codex, Gemini CLI) how to use Roxy UI when integrating RoxyAPI into a project.
+This file teaches AI coding agents (Claude Code, Cursor, Copilot, Codex, Gemini CLI, and any MCP-compatible client) how to use Roxy UI when integrating RoxyAPI into a project.
+
+This file ships inside both `@roxyapi/ui` and `@roxyapi/ui-react` on npm. After install, read it at `node_modules/@roxyapi/ui/AGENTS.md`.
+
+Live preview: <https://roxyapi.github.io/ui/>. Source of truth for component types: the OpenAPI spec at `roxyapi.com/openapi.json`, regenerated into `packages/ui/src/types/types.gen.ts`.
 
 ## Identity
 
@@ -8,7 +12,36 @@ Roxy UI is the official web component library for the RoxyAPI catalog. Component
 
 ## Decision tree for picking a component
 
-Use the table below. Match the user request against the endpoint, render the matching component.
+### Pick by user phrase
+
+Map the natural-language request to a component first; fall back to the table below if the request names a specific endpoint.
+
+| If the user says... | Render |
+|---|---|
+| "daily horoscope for `{sign}`", "weekly horoscope", "monthly horoscope" | `<roxy-horoscope-card>` |
+| "birth chart", "natal chart", "Western chart", "show me my planets" | `<roxy-natal-chart>` |
+| "match two birth charts", "compare us in Western astrology", "synastry" | `<roxy-synastry-chart>` |
+| "kundli", "Vedic chart", "rashi chart", "South/North Indian chart" | `<roxy-vedic-kundli>` |
+| "kundli matching", "Guna Milan", "match for marriage", "36-point compatibility" | `<roxy-guna-milan>` |
+| "are we compatible", "compatibility score", "love score" (cross-domain) | `<roxy-compatibility-card>` |
+| "panchang for today", "tithi", "nakshatra", "muhurta", "auspicious times" | `<roxy-panchang-table>` |
+| "dasha", "mahadasha", "current planetary period", "Vimshottari" | `<roxy-dasha-timeline>` |
+| "manglik", "kalsarpa", "sadhesati", "any doshas in my chart" | `<roxy-dosha-card>` |
+| "KP planets", "sub-lord", "Krishnamurti" | `<roxy-kp-planets-table>` |
+| "life path number", "expression number", "personal year", "numerology chart" | `<roxy-numerology-card>` |
+| "draw a tarot card", "card of the day", "card meaning" | `<roxy-tarot-card>` |
+| "tarot reading", "three-card spread", "Celtic Cross", "yes or no tarot" | `<roxy-tarot-spread>` |
+| "biorhythm", "physical/emotional/intellectual cycle", "critical days" | `<roxy-biorhythm-chart>` |
+| "I Ching", "hexagram", "cast the coins", "Book of Changes" | `<roxy-hexagram>` |
+| "moon phase", "moon calendar", "next full moon", "current moon" | `<roxy-moon-phase>` |
+| "search a city", "geocode", "lat/long for a place" | `<roxy-location-search>` |
+| "build a form for endpoint X" | `<roxy-endpoint-form>` |
+
+**Fallback rule.** If the response shape does not match any component above, render with `<roxy-data>`. It accepts any RoxyAPI response and produces a structured layout from the JSON.
+
+### Endpoint reference
+
+Use the table below for the formal endpoint to component mapping.
 
 <!-- BEGIN:COMPONENTS -->
 | Element | Domain | Endpoint(s) | What it renders |
@@ -45,6 +78,100 @@ Use the table below. Match the user request against the endpoint, render the mat
 | `<roxy-data>` | Helper | Any response shape | Generic fallback renderer for unknown shapes |
 <!-- END:COMPONENTS -->
 
+## Common integration bugs (read this first)
+
+These are the bugs that come up over and over. Read this section before writing the first line of integration code.
+
+### 1. Envelope not unwrapped
+
+The `@roxyapi/sdk` returns `{ data, error, request, response }`. **Always destructure `data` before passing to a component.** Passing the full envelope renders `[object Object]`. This is the single most common integration bug.
+
+```ts
+// Wrong: passes the envelope
+const response = await roxy.astrology.generateNatalChart({ body });
+element.data = response;  // → renders [object Object]
+
+// Right: unwrap data
+const { data } = await roxy.astrology.generateNatalChart({ body });
+element.data = data;
+```
+
+Every snippet below follows this rule.
+
+### 2. Hardcoded coordinates
+
+Every chart endpoint (Western, Vedic, KP, synastry, transits, dasha, dosha, panchang) needs `latitude`, `longitude`, and `timezone`. Never ask the user to type coordinates. Call `/location/search` first, then feed the result into the chart endpoint.
+
+```ts
+// Right
+const { data: cities } = await roxy.location.searchCities({ query: { q: 'Mumbai' } });
+const { latitude, longitude, timezone } = cities.cities[0];
+const { data: chart } = await roxy.astrology.generateNatalChart({
+  body: { date, time, latitude, longitude, timezone },
+});
+```
+
+### 3. Timezone format inconsistency
+
+Every chart endpoint accepts `timezone` as either a decimal-hour offset (`5.5` for IST, `-5` for EST) or an IANA name (`'Asia/Kolkata'`, `'America/New_York'`). The decimal form is what `/location/search` returns; the IANA form is correct over DST boundaries. Pick one and stay consistent in a single integration. Mixing them does not break the API but makes the bug surface area larger.
+
+### 4. Secret key in the browser
+
+There are two key classes. **Secret keys are unprefixed** and grant full access; they belong server-side only (Node, Bun, Hono, Next.js route handlers, Workers, Edge functions). **Publishable keys** are prefixed `pk_live_*` or `pk_test_*` and are safe in the browser; they are locked to an origin allowlist at the API gateway. For widgets, embeds, vanilla HTML, and `data-publishable-key` use the publishable key. For the typed SDK on a server, use the secret key.
+
+```ts
+// Server (Next.js route handler, Workers, Bun): secret key
+const roxy = createRoxy(process.env.ROXY_API_KEY!);
+
+// Browser (widgets auto-mount): publishable key
+<div data-roxy-widget="natal-chart" data-publishable-key="pk_live_xxx" ...></div>
+```
+
+### 5. Missing `'use client'` in Next.js App Router
+
+The React components in `@roxyapi/ui-react` mount Custom Elements, which need the DOM. In the App Router, files that import them must declare `'use client'` at the top. Server Components can fetch with the SDK; the client component renders.
+
+```tsx
+// app/chart-view.tsx
+'use client';
+import { RoxyNatalChart } from '@roxyapi/ui-react';
+
+export default function ChartView({ data }) {
+  return <RoxyNatalChart data={data} />;
+}
+```
+
+### 6. React 17 or 18 swallowing custom events
+
+React 19 routes hyphenated DOM events through camelCase props correctly. React 17 and 18 do not. On 17/18, attach the listener with a ref:
+
+```tsx
+const ref = useRef<HTMLElement>(null);
+useEffect(() => {
+  const el = ref.current;
+  if (!el) return;
+  const handler = (e: Event) => setData((e as CustomEvent).detail);
+  el.addEventListener('roxy-location-select', handler);
+  return () => el.removeEventListener('roxy-location-select', handler);
+}, []);
+
+return <roxy-location-search ref={ref} />;
+```
+
+The React 19 path is `<RoxyLocationSearch onRoxyLocationSelect={handler} />`.
+
+### 7. Local response interface drift
+
+Do not declare `interface XyzData { ... }` for a RoxyAPI response. Import the spec-derived type from `@roxyapi/sdk` (or let the SDK return type flow through inference). Local interfaces drift the moment the spec changes; the component will keep compiling while rendering nothing.
+
+```ts
+// Wrong
+interface NatalChart { planets: ...; houses: ...; }
+
+// Right
+import type { NatalChartResponse } from '@roxyapi/sdk';
+```
+
 ## Integration patterns
 
 ### Pattern 1: vanilla HTML, no build step
@@ -58,18 +185,11 @@ Use the table below. Match the user request against the endpoint, render the mat
 <roxy-natal-chart id="chart"></roxy-natal-chart>
 
 <script type="module">
-	const res = await fetch('https://roxyapi.com/api/v2/astrology/natal-chart', {
-		method: 'POST',
-		headers: { 'Content-Type': 'application/json', 'X-API-Key': 'roxy_xxx' },
-		body: JSON.stringify({
-			date: '1990-01-15',
-			time: '14:30:00',
-			latitude: 28.6139,
-			longitude: 77.209,
-			timezone: 5.5,
-		}),
+	import { createRoxy } from 'https://cdn.jsdelivr.net/npm/@roxyapi/sdk@latest/dist/factory.js';
+	const roxy = createRoxy('pk_live_xxx');
+	const { data } = await roxy.astrology.generateNatalChart({
+		body: { date: '1990-01-15', time: '14:30:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5 },
 	});
-	const data = await res.json();
 	document.getElementById('chart').data = data;
 </script>
 ```
@@ -77,25 +197,33 @@ Use the table below. Match the user request against the endpoint, render the mat
 ### Pattern 2: React, with the typed SDK
 
 ```tsx
+'use client';
+
 import { createRoxy } from '@roxyapi/sdk';
-import { RoxyNatalChart, RoxyLocationSearch } from '@roxyapi/ui-react';
+import {
+	RoxyNatalChart,
+	RoxyLocationSearch,
+	type RoxyNatalChartProps,
+} from '@roxyapi/ui-react';
 import { useState } from 'react';
 
 const roxy = createRoxy(process.env.NEXT_PUBLIC_ROXY_API_KEY!);
 
 export function BirthChartView() {
-	const [chart, setChart] = useState(null);
+	const [chart, setChart] = useState<RoxyNatalChartProps['data']>(undefined);
 
-	const onLocationSelect = async (e: CustomEvent<{ latitude: number; longitude: number; timezone: string }>) => {
+	const onLocationSelect = async (e: CustomEvent<{ latitude?: number; longitude?: number; timezone?: number | string }>) => {
+		const { latitude, longitude, timezone } = e.detail;
+		if (latitude == null || longitude == null) return;
 		const { data } = await roxy.astrology.generateNatalChart({
-			body: { date: '1990-01-15', time: '14:30:00', ...e.detail },
+			body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone },
 		});
 		setChart(data);
 	};
 
 	return (
 		<div>
-			<RoxyLocationSearch onroxy-location-select={onLocationSelect} />
+			<RoxyLocationSearch onRoxyLocationSelect={onLocationSelect} />
 			{chart && <RoxyNatalChart data={chart} />}
 		</div>
 	);
@@ -114,15 +242,12 @@ export function BirthChartView() {
 ></roxy-endpoint-form>
 
 <script type="module">
+	import { createRoxy } from 'https://cdn.jsdelivr.net/npm/@roxyapi/sdk@latest/dist/factory.js';
+	const roxy = createRoxy('pk_live_xxx');
 	const form = document.querySelector('roxy-endpoint-form');
 	form.addEventListener('roxy-submit', async (e) => {
-		const { endpoint, values } = e.detail;
-		const res = await fetch(`https://roxyapi.com/api/v2/${endpoint}`, {
-			method: 'POST',
-			headers: { 'Content-Type': 'application/json', 'X-API-Key': 'roxy_xxx' },
-			body: JSON.stringify(values),
-		});
-		const kundli = await res.json();
+		const { values } = e.detail;
+		const { data: kundli } = await roxy.vedicAstrology.generateBirthChart({ body: values });
 		document.querySelector('roxy-vedic-kundli').data = kundli;
 	});
 </script>
@@ -130,7 +255,7 @@ export function BirthChartView() {
 
 ### Pattern 4: widgets auto-mount (no JavaScript wiring)
 
-Use the publishable key flow for vibecoder embeds.
+Use a publishable key (`pk_live_*` or `pk_test_*`) for client-side embeds. Get one at <https://roxyapi.com/account>. Publishable keys are origin-restricted at the API gateway. Register the customer domain (e.g. `https://customer.com`) when creating the key, and the gateway will reject requests from any other origin. Never use a secret key in client-side code (secret keys are unprefixed and live server-side only).
 
 ```html
 <script
@@ -151,14 +276,84 @@ Use the publishable key flow for vibecoder embeds.
 
 The auto-mount script reads `data-*` attributes, calls the matching endpoint, and renders the matching component.
 
+### Pattern 5: MCP tool-call response
+
+A remote MCP server at `roxyapi.com/mcp/{domain}` exposes each RoxyAPI endpoint as an MCP tool. The JSON returned by the tool call has the same shape as the SDK response. Pass it straight into the matching component.
+
+```ts
+// Pseudocode for any MCP-aware agent
+const result = await mcp.call('roxyapi.astrology.generate_natal_chart', {
+	date: '1990-01-15', time: '14:30:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5,
+});
+document.querySelector('roxy-natal-chart').data = result;
+```
+
+No field renames. No glue code. Use the decision tree above to pick the component for any tool.
+
+### Pattern 6: Next.js RSC streaming
+
+Server fetches with the secret key, client renders with the React component. The API key never crosses the network.
+
+```tsx
+// app/page.tsx (Server Component)
+import { createRoxy } from '@roxyapi/sdk';
+import BirthChartView from './birth-chart-view';
+
+const roxy = createRoxy(process.env.ROXY_API_KEY!);
+
+export default async function Page() {
+	const { data } = await roxy.vedicAstrology.generateBirthChart({
+		body: { date: '1990-01-15', time: '14:30:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5 },
+	});
+	return <BirthChartView data={data} />;
+}
+```
+
+```tsx
+// app/birth-chart-view.tsx (Client Component)
+'use client';
+import { RoxyVedicKundli } from '@roxyapi/ui-react';
+
+export default function BirthChartView({ data }: { data: unknown }) {
+	return <RoxyVedicKundli data={data} />;
+}
+```
+
+## Theming and dark mode
+
+Components react to three signals in priority order. No events to dispatch. No JS bridge to write.
+
+| Signal | Where | Effect |
+|---|---|---|
+| `prefers-color-scheme: dark` | OS | Default. Follows user system setting. |
+| `data-theme="light"` or `data-theme="dark"` | `<html>` / `<body>` / any ancestor / the component itself | Wins over OS. Per-element override scope works. |
+| `.dark` class | Any ancestor | Equivalent to `data-theme="dark"`. Use when the host stack already ships a `.dark` toggle (Tailwind, shadcn). |
+
+To toggle at runtime:
+
+```ts
+document.documentElement.dataset.theme = 'dark'; // or 'light'
+```
+
+That single line re-themes every Roxy UI component on the page. Persist user choice in `localStorage` from your own code; the library does not own preferences.
+
+Per-element scope is supported:
+
+```html
+<roxy-natal-chart data-theme="dark" .data=${chart}></roxy-natal-chart>
+```
+
+Every visible aspect of the chart is driven by `--roxy-*` CSS custom properties on `:host`. Override any token on `:root`, on `:host`, or per element. Do not write Tailwind utility classes inside the components; the Shadow DOM boundary stops them at the door.
+
 ## Rules every agent must follow
 
 - Always call `/location/search` first before any chart endpoint that takes latitude, longitude, or timezone. Use `<roxy-location-search>` for the input UI.
 - Pass the response object directly. Components are stateless; they do not fetch internally except for `<roxy-location-search>`, `<roxy-endpoint-form>`, and the widgets auto-mount script.
 - Use the typed SDK from `@roxyapi/sdk` so prop shapes match the spec automatically.
-- Theming is CSS custom properties on `:root` or per element. Do not write Tailwind classes inside the components; the shadow DOM ignores them.
+- Theming is CSS custom properties on `:root` or per element. Switch light and dark via `data-theme` on any ancestor (see the table above). Do not write Tailwind classes inside the components; the shadow DOM ignores them.
 - Honor reduced motion. The library already respects `prefers-reduced-motion: reduce` and the `--roxy-motion-duration` variable.
 - A11y violations are CI failures. Do not paste over `role` or `aria-*` attributes; the components emit them correctly already.
+- Component types come from the OpenAPI spec via `@hey-api/openapi-ts`. Do not redefine response shapes locally; if a field is missing, fix the spec, regenerate, propagate.
 
 ## Domain ordering
 
@@ -166,10 +361,14 @@ When listing domains in user-visible copy, use the canonical order: Western astr
 
 ## What not to ship
 
-- Do not bundle `@roxyapi/ui` and `@roxyapi/ui-react` together; they are decoupled by design.
+- Do not bundle `@roxyapi/ui` and `@roxyapi/ui-react` together; they ship independently.
 - Use `@roxyapi/ui-react` for React projects. Use `@roxyapi/ui` directly elsewhere.
 - Do not write your own kundli component. The lifted layout in `<roxy-vedic-kundli>` is the canonical RoxyAPI render path.
 - Do not call astrology endpoints with hardcoded coordinates. Always geocode first via `<roxy-location-search>` or `roxy.location.searchCities()`.
+- Do not declare a local `interface XyzData` to describe a RoxyAPI response. Import the type from the spec-derived bundle: `import type { XyzResponse } from '@roxyapi/sdk'`. Local interfaces drift the moment the spec changes.
+- Do not write Tailwind utility classes inside a component. The Shadow DOM boundary stops them at the door. Theme through `--roxy-*` CSS custom properties on `:root` or per element instead.
+- Do not fetch inside chart, table, or card components. They are stateless: pass `data` as a prop. Documented exceptions are `<roxy-location-search>`, `<roxy-endpoint-form>`, and the widgets auto-mount script.
+- Do not redefine theme tokens or invent your own naming. Override the existing `--roxy-*` custom properties; the full list is in `THEMING.md`.
 
 ## Where to look next
 
@@ -177,4 +376,4 @@ When listing domains in user-visible copy, use the canonical order: Western astr
 - Sample data for every component: `apps/docs/sample-data.js`
 - Token reference: `packages/ui/THEMING.md`
 - Live preview: `bun run preview` then open `http://localhost:3001`
-- Money endpoints reference: see the RoxyAPI methodology page at `roxyapi.com/methodology`
+- Endpoint reference: <https://roxyapi.com/api-reference>