@sanvika/astro

Thin S2S HTTP client for the Sanvika Astro service (astro.sanvikaproduction.com). Vedic Kundli, Manglik, 36-guna Ashtakoota and explainable pair scoring — all compute is owned by the service. This package contains zero ephemeris / engine math (fleet rule §4.1a / §20).

Current version: 2.1.0 — see CHANGELOG.md and docs/professional-report-payload.md.

Install

pnpm add @sanvika/[email protected]

What's New in 2.1

Professional Report Payload evolution (still Astro v1 line — additive):

• professionalReport on computeChart / analyzeMatchmaking
• Render-ready ChartRenderPayload for D1 + D9 (+ all vargas)
• ConsultationProse + ordered ReportChapter[]
• Muhurat pdfRows

What's New in 2.0

Canonical Dictionary + Identity platform. Consumers render typed contracts; they never recalculate astrology.

Identity builders live on the service / @sanvika/astro-engine/server. This SDK exports the matching TypeScript contracts and the HTTP client that returns birthProfile from computeChart().

import type {
  BirthProfile,
  PlanetaryIdentity,
  HouseIdentity,
  DoshaIdentity,
  CompatibilityIdentity,
} from "@sanvika/astro/types";

// Service HTTP: Birth Identity on every chart response
import { SanvikaAstroClient } from "@sanvika/astro/server";
const astro = SanvikaAstroClient.fromProcessEnv();
const chartRes = await astro.computeChart({ birth: { /* … */ } });
const birthProfile: BirthProfile = chartRes.birthProfile;

// Engine surface (service process) — same contracts:
// getBirthProfile(chart)
// getPlanetaryIdentities(chart)      → PlanetaryIdentity[]
// getHouseIdentities(chart)          → HouseIdentity[]
// getDoshaIdentities(chart)          → { doshas, present }
// toCompatibilityIdentity(analysis) → CompatibilityIdentity

Env (server-side only — never NEXT_PUBLIC_)

ASTRO_URL=https://astro.sanvikaproduction.com
ASTRO_CLIENT_ID=<your registered clientId>
ASTRO_CLIENT_SECRET=<plain secret from the astro admin panel>
# Optional Tier-1 fleet trust:
SANVIKA_SERVICE_KEY=<shared fleet service key>

Usage (server / Next.js API route)

import { SanvikaAstroClient } from "@sanvika/astro/server";

const astro = SanvikaAstroClient.fromProcessEnv();

// 1) Upsert a user's birth → service computes + stores the chart (SSOT)
const up = await astro.upsertProfile({
  uid: "u_123",
  birth: { date: "1995-08-15", time: "14:30", place: "Varanasi, India", gender: "male" },
});
// up.ok, up.profile.astroReady, up.profile.summary.moonRashiName …

// 2) Read a stored profile summary
const got = await astro.getProfile({ uid: "u_123" });

// 3) Pair compatibility by two stored uids (matchmaking)
const pair = await astro.scorePair({ uidA: "u_123", uidB: "u_456" });
// pair.result.astroScore (0..100), pair.result.gunaTotal, pair.result.reasons[{key,params}]

// Stateless compute (no storage):
const chartRes = await astro.computeChart({ birth: { /* … */ } });
chartRes.birthProfile.rashi.id;     // e.g. "vrishabha"
chartRes.birthProfile.nakshatra.id; // e.g. "rohini"
chartRes.birthProfile.lagna?.id;    // null if birth time unreliable
chartRes.birthProfile.moon.longitude;
chartRes.birthProfile.metadata.algoVersion;
// Resolve explain keys via @sanvika/lang — never invent astrology prose:
// chartRes.birthProfile.rashi.description
// chartRes.birthProfile.rashi.characteristics / strengths / watchPoints

await astro.gunaMilan({ boy: { /* … */ }, girl: { /* … */ } });
await astro.manglik({ birth: { /* … */ } });

Every method is error-safe: it returns { ok: true, … } on success or { ok: false, code, status?, message? } on failure (never throws on network / service errors).

BirthProfile (canonical birth identity)

computeChart() returns a canonical birthProfile owned by the engine and typed by this SDK. Consumers render it; they must not recompute rashi / nakshatra / lagna or invent explanations.

import type { BirthProfile } from "@sanvika/astro/types";

Top-level fields

| Field | Type | Notes | |---|---|---| | rashi | BirthProfileRashi | Chandra rashi (Moon sign) | | nakshatra | BirthProfileNakshatra | Moon nakshatra + pada / gana / yoni / nadi | | lagna | BirthProfileLagna \| null | null when birth time is unreliable | | moon | BirthProfileMoon | Sidereal longitude + lightweight sign/nakshatra refs | | metadata | BirthProfileMetadata | Ayanamsa, system, versions for audit |

rashi

| Field | Example | Notes | |---|---|---| | id | "vrishabha" | Stable id (localization / icons) | | name | "Vrishabha" | Sanskrit/Hindi convenience label | | english | "Taurus" | English zodiac convenience label | | lord | "venus" | Rashi lord (BirthProfilePlanetId) | | element | "earth" | fire | earth | air | water | | modality | "fixed" | cardinal | fixed | mutable | | number | 2 | 1-based sign number | | description | "birth.rashi.vrishabha.description" | i18n key | | characteristics | string[] | Educational i18n keys | | strengths | string[] | Positive-trait i18n keys | | watchPoints | string[] | Awareness i18n keys |

nakshatra

| Field | Example | Notes | |---|---|---| | id | "rohini" | Stable id | | name | "Rohini" | Sanskrit/Hindi label | | english | "Rohini" | English label | | pada | 2 | 1..4 | | lord | "moon" | Vimshottari dasha lord | | gana | "manushya" | deva | manushya | rakshasa | | yoni.id | "serpent" | Yoni animal id | | yoni.name | "Sarpa" | Sanskrit/Hindi yoni label | | yoni.english | "Serpent" | English yoni label | | nadi | "antya" | aadi | madhya | antya | | description | "birth.nakshatra.rohini.description" | i18n key | | characteristics | string[] | Educational i18n keys | | strengths | string[] | Positive-trait i18n keys | | watchPoints | string[] | Awareness i18n keys |

lagna

| Field | Example | Notes | |---|---|---| | id | "tula" | Ascendant sign id | | name | "Tula" | Sanskrit/Hindi label | | english | "Libra" | English label | | lord | "venus" | Lagna lord | | description | "birth.lagna.tula.description" | i18n key | | characteristics | string[] | Educational i18n keys | | strengths | string[] | Positive-trait i18n keys | | watchPoints | string[] | Awareness i18n keys |

moon

| Field | Example | Notes | |---|---|---| | longitude | 42.1847 | Sidereal longitude [0, 360) | | sign | { id, name, english } | Moon rashi reference | | nakshatra | { id, name, english, pada } | Moon nakshatra reference |

metadata

| Field | Example | Notes | |---|---|---| | ayanamsha | "lahiri" | Ayanamsa used | | calculationSystem | "whole-sign-astronomy-engine" | House + ephemeris label | | timezone | "2025a" | TZDATA version from engine stamp | | engineVersion | "0.2.0" | Engine version | | algoVersion | "north-indian-v2" | Algo / cache-invalidation version |

Prefer stable id values + @sanvika/lang for user-visible copy. Treat name / english as convenience defaults only.

Identity contracts (Phases C–J)

Additive TypeScript contracts for fleet apps (engine builds these; SDK types them):

import type {
  ExplainProfile,
  PlanetaryIdentity,
  HouseIdentity,
  DoshaIdentity,
  YogaIdentity,
  CompatibilityIdentity,
  PredictionIdentity,
  ReportIdentity,
} from "@sanvika/astro/types";

Consumers render identities. They must not recompute astrology or invent explanation prose — resolve ExplainProfile keys via @sanvika/lang.

Types + display constants

import { RASHIS, NAKSHATRAS, rashiName, nakshatraName } from "@sanvika/astro";
import {
  RASHI_ENTRIES,
  NAKSHATRA_ENTRIES,
  PLANET_ENTRIES,
  GANA_ENTRIES,
  YONI_ENTRIES,
  NADI_ENTRIES,
  ELEMENT_ENTRIES,
  rashiById,
  nakshatraById,
  planetById,
  ganaById,
  yoniById,
  nadiById,
} from "@sanvika/astro";
import type {
  PairScoreResult,
  AstroProfileSummary,
  BirthInput,
  BirthProfile,
  BirthProfileRashi,
  BirthProfileNakshatra,
  BirthProfileLagna,
  BirthProfileMoon,
  BirthProfileMetadata,
} from "@sanvika/astro/types";

Reason keys are returned as { key, params } — resolve them in your app via @sanvika/lang / t(key, params).

Canonical dictionaries

SDK exposes canonical lookup dictionaries under src/data/ so every consumer uses the same stable IDs and display names:

import {
  RASHI_ENTRIES,
  NAKSHATRA_ENTRIES,
  PLANET_ENTRIES,
  GANA_ENTRIES,
  YONI_ENTRIES,
  NADI_ENTRIES,
  ELEMENT_ENTRIES,
} from "@sanvika/astro";

These are pure display mirrors; computation remains server-side in @sanvika/astro-engine.