lifeastroapi 0.0.0-stage → 0.3.0
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.
- package/LICENSE +21 -0
- package/README.md +513 -2
- package/dist/index.cjs +2028 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +1776 -0
- package/dist/index.d.ts +1776 -0
- package/dist/index.js +1991 -0
- package/dist/index.js.map +1 -0
- package/dist/pdf/index.cjs +4947 -0
- package/dist/pdf/index.cjs.map +1 -0
- package/dist/pdf/index.d.cts +1277 -0
- package/dist/pdf/index.d.ts +1277 -0
- package/dist/pdf/index.js +4894 -0
- package/dist/pdf/index.js.map +1 -0
- package/package.json +100 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ayanshu Life
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,514 @@
|
|
|
1
|
-
#
|
|
1
|
+
# lifeastroapi
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Official **Node.js / TypeScript SDK** for [LifeAstroAPI](https://lifeastroapi.com) — a
|
|
4
|
+
B2B Vedic & Western astrology API with panchang-grade precision and
|
|
5
|
+
pay-per-call billing.
|
|
6
|
+
|
|
7
|
+
- ✅ **All 311 endpoints**, fully typed, across 23 namespaces — panchang, charts, dashas,
|
|
8
|
+
matchmaking, transits, horoscopes, numerology, tarot, muhurta, reports, narratives,
|
|
9
|
+
and a complete Western (tropical) module.
|
|
10
|
+
- ✅ **Zero runtime dependencies** — uses the platform `fetch` (Node 18+, Bun, Deno,
|
|
11
|
+
and edge / serverless runtimes). Server-side by design — see [Authentication](#authentication).
|
|
12
|
+
- ✅ **ESM + CommonJS** with bundled `.d.ts` types.
|
|
13
|
+
- ✅ Typed errors, automatic retries (429/5xx) with `Retry-After`, timeouts, and a
|
|
14
|
+
generic escape hatch for any endpoint.
|
|
15
|
+
- ✅ **Branded PDF reports** (optional) — turn report JSON into white-label,
|
|
16
|
+
print-ready kundli / matchmaking / numerology / horoscope PDFs. Rendering needs
|
|
17
|
+
Puppeteer (a headless Chrome), installed separately — see
|
|
18
|
+
[Branded PDF reports](#branded-pdf-reports).
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
npm install lifeastroapi
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Get an API key at **https://lifeastroapi.com/dashboard/keys**.
|
|
25
|
+
|
|
26
|
+
## Quick start
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import { LifeAstro } from "lifeastroapi";
|
|
30
|
+
|
|
31
|
+
const client = new LifeAstro({ apiKey: "dv_live_..." });
|
|
32
|
+
// or: new LifeAstro({ apiKey: process.env.LIFEASTRO_API_KEY })
|
|
33
|
+
// or just: new LifeAstro("dv_live_...")
|
|
34
|
+
|
|
35
|
+
// Today's panchang for a location
|
|
36
|
+
const tithi = await client.panchang.tithi({
|
|
37
|
+
lat: 28.6139,
|
|
38
|
+
lon: 77.209,
|
|
39
|
+
tz: "Asia/Kolkata",
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
// A Vedic birth chart
|
|
43
|
+
const planets = await client.chart.planets({
|
|
44
|
+
date: "1990-01-15",
|
|
45
|
+
time: "10:30",
|
|
46
|
+
tz: "Asia/Kolkata",
|
|
47
|
+
lat: 19.076,
|
|
48
|
+
lon: 72.8777,
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
// Kundli matchmaking score
|
|
52
|
+
const match = await client.milan.ashtakootaTotal({
|
|
53
|
+
boy: { date: "1988-05-04", time: "06:15", tz: "Asia/Kolkata", lat: 28.61, lon: 77.20 },
|
|
54
|
+
girl: { date: "1992-03-20", time: "21:40", tz: "Asia/Kolkata", lat: 19.07, lon: 72.87 },
|
|
55
|
+
});
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
> CommonJS works too: `const { LifeAstro } = require("lifeastroapi");`
|
|
59
|
+
|
|
60
|
+
## Authentication
|
|
61
|
+
|
|
62
|
+
Your API key (`dv_live_…`) authenticates every request and is sent as a
|
|
63
|
+
`Authorization: Bearer …` header. Provide it in any of three ways:
|
|
64
|
+
|
|
65
|
+
```ts
|
|
66
|
+
new LifeAstro({ apiKey: "dv_live_..." }); // 1. explicit (recommended)
|
|
67
|
+
new LifeAstro("dv_live_..."); // 2. shorthand
|
|
68
|
+
new LifeAstro(); // 3. reads process.env.LIFEASTRO_API_KEY
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
If no key is found (neither argument nor env var), the constructor throws a clear
|
|
72
|
+
error. Get a key at **https://lifeastroapi.com/dashboard/keys**.
|
|
73
|
+
|
|
74
|
+
> ### 🔒 Keep your key secret — use the SDK server-side
|
|
75
|
+
> A `dv_live_…` key carries your account's **full billing access**. Use this SDK from a
|
|
76
|
+
> **server, serverless function, or edge runtime** — and load the key from an environment
|
|
77
|
+
> variable / secrets manager, never hard-coded. **Do not embed the key in browser, mobile,
|
|
78
|
+
> desktop, or any client-side code**, where end users could extract it and run up your bill.
|
|
79
|
+
> For client apps, call LifeAstroAPI from your own backend and forward the results.
|
|
80
|
+
>
|
|
81
|
+
> (Need PDFs in the browser? The dependency-free `lifeastroapi/pdf` `render*Html`
|
|
82
|
+
> functions take **no key** and are safe to run anywhere — see [Branded PDF reports](#branded-pdf-reports).)
|
|
83
|
+
|
|
84
|
+
## Configuration
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
const client = new LifeAstro({
|
|
88
|
+
apiKey: "dv_live_...", // or set LIFEASTRO_API_KEY
|
|
89
|
+
baseUrl: "https://api.lifeastroapi.com", // override for local dev (http://localhost:8080)
|
|
90
|
+
timeoutMs: 30_000, // per-request timeout (default 30s)
|
|
91
|
+
maxRetries: 2, // retries on 429 / 5xx / network (default 2)
|
|
92
|
+
defaultHeaders: {}, // extra headers on every request
|
|
93
|
+
fetch: myFetch, // inject a custom fetch (older runtimes / proxies / tests)
|
|
94
|
+
});
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Input shapes
|
|
98
|
+
|
|
99
|
+
Most methods accept one of a few ergonomic input objects. The SDK maps these to the
|
|
100
|
+
exact wire parameters the API expects (`birth.lat`, `boy.date`, `start_date`, …) for you.
|
|
101
|
+
|
|
102
|
+
| Shape | Used by | Example fields |
|
|
103
|
+
|-------|---------|----------------|
|
|
104
|
+
| **Moment** | `panchang.*`, `muhurta.*` (single date), `prashna.*` | `{ lat, lon, tz, date?, time? }` |
|
|
105
|
+
| **Instant** | `transit.positions`, `transit.doubleTransit`, `meta.ayanamsas` | `{ date?, time?, tz? }` |
|
|
106
|
+
| **Birth** | `chart.*`, `dasha.*`, `numerology`, narratives, reports | `{ date, time, tz, lat, lon }` |
|
|
107
|
+
| **Boy/Girl** | `milan.*`, `reports.matchMaking` | `{ boy: Birth, girl: Birth }` |
|
|
108
|
+
| **Two-person** | `western.synastry.*`, `western.composite.*` | `{ personA: Birth, personB: Birth }` |
|
|
109
|
+
| **Rashi** | `horoscope.*` | `{ rashi: "aries", date?, lang? }` |
|
|
110
|
+
| **Date range** | `eclipses.*`, `western.ingresses` | `{ startDate, endDate }` |
|
|
111
|
+
| **Muhurta (search)** | `muhurta.bestTime` | `{ lat, lon, tz, startDate, endDate }` |
|
|
112
|
+
| **Natal + transit** | `transit.tarabala`, `transit.vedha`, `western.transits.toNatal` | `{ birth: Birth, date, time, tz }` |
|
|
113
|
+
|
|
114
|
+
**Dates.** The API requires a `date` on every moment endpoint — it has no "today"
|
|
115
|
+
default. Where a shape marks `date?` optional, the SDK sends today's date in the `tz`
|
|
116
|
+
you gave. The per-purpose muhurta methods (`muhurta.vivah`, `grahaPravesh`, …) score
|
|
117
|
+
**one** date per call; to search a range for the best dates use `muhurta.bestTime`.
|
|
118
|
+
|
|
119
|
+
**Personalised horoscopes** (`narrative.horoscopeDailyByLagna`, `…ByMoon`, `…Tamil`,
|
|
120
|
+
`horoscopeWeeklyBy…`) take the **birth** chart as their input; pass `onDate`
|
|
121
|
+
(`YYYY-MM-DD`) to read a day other than today.
|
|
122
|
+
|
|
123
|
+
Vedic endpoints also accept optional calculation settings: `ayanamsa`
|
|
124
|
+
(`"lahiri"` default, `"krishnamurti"`, `"raman"`, …) and `houseSystem`.
|
|
125
|
+
|
|
126
|
+
```ts
|
|
127
|
+
await client.chart.planets({ ...birth, ayanamsa: "krishnamurti", houseSystem: "placidus" });
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## Namespaces
|
|
131
|
+
|
|
132
|
+
`client.<namespace>.<method>(input)` — every method returns the response payload.
|
|
133
|
+
|
|
134
|
+
| Namespace | What it covers |
|
|
135
|
+
|-----------|----------------|
|
|
136
|
+
| `panchang` | tithi, nakshatra, yoga, karana, vara, sunrise/sunset, rahu-kaal, choghadiya, hora, muhurtas, monthly calendar, composite `basic`/`advanced` |
|
|
137
|
+
| `chart` | planets, ascendant, houses, divisional (D1–D60), dignity, aspects, shadbala, ashtakvarga, avakhada, KP, astro-details |
|
|
138
|
+
| `dasha` | full + current Vimshottari (5-level drill-down) and Yogini |
|
|
139
|
+
| `milan` | Ashtakoota (total / full / per-koota), mangal/nadi/shani dosha, navamsa & dasha compatibility |
|
|
140
|
+
| `transit` | positions, sade-sati, ashtakavarga, tarabala, vedha, double-transit, small-panoti |
|
|
141
|
+
| `horoscope` | daily / weekly / monthly by rashi |
|
|
142
|
+
| `numerology` | driver, conductor, soul, personality, destiny, full, advanced, challenges, personalPeriods |
|
|
143
|
+
| `muhurta` | vivah, naamkaran, griha-pravesh, vyapar, yatra, best-time, … |
|
|
144
|
+
| `varshaphal` | annual chart, lord, muntha, mudda-dasha, harsha-bala, tajika yogas |
|
|
145
|
+
| `prashna` | horary answer, chart, arudha, significators |
|
|
146
|
+
| `eclipses` | solar / lunar / all (date range, optional visibility) |
|
|
147
|
+
| `calendar` | Hindu month, ritu, samvatsara, adhik-maas |
|
|
148
|
+
| `festivals` | full Hindu festival calendar by month / on a date — location-aware, `locale`, `monthSystem` (amanta/purnimanta); `panchang.monthly({ include: "sheet" })` returns a complete printable calendar page |
|
|
149
|
+
| `planetMoments` | retrograde windows, ingress, combustion window, speed |
|
|
150
|
+
| `ashtakavarga` | sarva, bhinna (per planet), kaksha, transit-score |
|
|
151
|
+
| `geo` | place search, reverse geocode, timezone, place by id |
|
|
152
|
+
| `tarot` | cards, single card, daily, spread, yes/no |
|
|
153
|
+
| `reports` | kundli (lite/detailed/brihad), match-making, mangal-dosha, sade-sati, varshaphal, numerology, horoscopes |
|
|
154
|
+
| `narrative` | authored Vedic interpretations (lagna, planets, yogas, doshas, dasha-phal, outlooks, …) in `en/hi/mr/bn/kn/ta/te/gu` |
|
|
155
|
+
| `remedies` | remedies by rule id; mantra / pooja / vrat / daan / rudraksha / yantra detail; Lal Kitab remedies |
|
|
156
|
+
| `lalkitab` | Lal Kitab chart and dasha |
|
|
157
|
+
| `meta` | free catalogs: `endpoints` (credit cost of every route), `ayanamsas`, `vedicYogas`, `vedicDoshas`, `vedicLocales`, `version` |
|
|
158
|
+
| `western` | full tropical module (see below) |
|
|
159
|
+
|
|
160
|
+
### Western (tropical)
|
|
161
|
+
|
|
162
|
+
Nested under `client.western.*`:
|
|
163
|
+
|
|
164
|
+
```ts
|
|
165
|
+
await client.western.natal.chart({ date, time, tz, lat, lon, houseSystem: "placidus" });
|
|
166
|
+
await client.western.synastry.score({ personA, personB });
|
|
167
|
+
await client.western.transits.toNatal({ birth, date: "2026-06-16", time: "12:00", tz: "UTC" });
|
|
168
|
+
await client.western.returns.solar({ date, time, tz, lat, lon, returnYear: 2026 });
|
|
169
|
+
await client.western.profections.annual({ birthDate: "1990-01-15", ascSign: "capricorn" });
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Sub-namespaces: `natal`, `horoscope`, `synastry`, `composite`, `davison`, `transits`,
|
|
173
|
+
`progressions`, `solarArc`, `returns`, `dignities`, `profections`, `zodiacalReleasing`,
|
|
174
|
+
`primaryDirections`, `interpretation`, `narrative`, `heliocentric`, `astrocartography`,
|
|
175
|
+
`eclipses`, `lunar`, `compatibility`, plus `firdaria`, `ingresses`, `retrogradeWindow`.
|
|
176
|
+
|
|
177
|
+
## Error handling
|
|
178
|
+
|
|
179
|
+
Every non-2xx response throws a typed error carrying the API's `code`, HTTP `status`,
|
|
180
|
+
and `request_id`:
|
|
181
|
+
|
|
182
|
+
```ts
|
|
183
|
+
import { LifeAstro, PaymentRequiredError, RateLimitError, LifeAstroError } from "lifeastroapi";
|
|
184
|
+
|
|
185
|
+
try {
|
|
186
|
+
await client.chart.planets(birth);
|
|
187
|
+
} catch (err) {
|
|
188
|
+
if (err instanceof PaymentRequiredError) {
|
|
189
|
+
// 402 — out of credits / trial exhausted
|
|
190
|
+
} else if (err instanceof RateLimitError) {
|
|
191
|
+
console.log(`retry after ${err.retryAfter}s`);
|
|
192
|
+
} else if (err instanceof LifeAstroError) {
|
|
193
|
+
console.error(err.code, err.status, err.message, err.requestId);
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Error classes: `BadRequestError` (400), `AuthenticationError` (401),
|
|
199
|
+
`PaymentRequiredError` (402), `PermissionError` (403), `NotFoundError` (404),
|
|
200
|
+
`RateLimitError` (429), `ServerError` (5xx), `LifeAstroConnectionError` (network/timeout).
|
|
201
|
+
All extend `LifeAstroError`.
|
|
202
|
+
|
|
203
|
+
## Typing the response
|
|
204
|
+
|
|
205
|
+
The API returns each payload directly as JSON (there is no `{ data, meta }` wrapper),
|
|
206
|
+
and the SDK hands it back typed `unknown` by default. Narrow it with a type parameter:
|
|
207
|
+
|
|
208
|
+
```ts
|
|
209
|
+
interface TithiData { number: number; name_en: string; paksha: string }
|
|
210
|
+
const t = await client.panchang.tithi<TithiData>({ lat, lon, tz });
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
## Escape hatch
|
|
214
|
+
|
|
215
|
+
Call any `/v1/*` endpoint directly — useful for brand-new endpoints not yet wrapped:
|
|
216
|
+
|
|
217
|
+
```ts
|
|
218
|
+
const data = await client.request("/v1/panchang/tithi", { lat: 28.61, lon: 77.20, tz: "Asia/Kolkata" });
|
|
219
|
+
// client.get(...) is an alias
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
## Per-call options
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
const controller = new AbortController();
|
|
226
|
+
await client.chart.planets(birth, { signal: controller.signal, timeoutMs: 5000 });
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
## Branded PDF reports
|
|
230
|
+
|
|
231
|
+
The `lifeastroapi/pdf` subpath turns the JSON from `client.reports.*` into
|
|
232
|
+
**branded, print-ready PDFs** — cover page, charts, planet and dasha tables,
|
|
233
|
+
narrative sections — white-labelled with your logo, colours, footer and optional
|
|
234
|
+
watermark.
|
|
235
|
+
|
|
236
|
+
The API itself returns **JSON only**. The PDF is built on **your** server, by this
|
|
237
|
+
SDK. That keeps your branding and your customers' reports on your side, and it is
|
|
238
|
+
why PDF rendering has requirements the rest of the SDK does not.
|
|
239
|
+
|
|
240
|
+
### Two layers
|
|
241
|
+
|
|
242
|
+
| Layer | Functions | Needs |
|
|
243
|
+
|---|---|---|
|
|
244
|
+
| **HTML** | `render*Html(data, branding?)` | Nothing. Pure string functions with zero dependencies; run on Node, serverless, edge or in a browser. |
|
|
245
|
+
| **PDF** | `*Pdf(data, opts?)`, `htmlToPdf(html, opts?)` | A headless Chromium, driven through **Puppeteer** (see below). |
|
|
246
|
+
|
|
247
|
+
If you only call the API, or only need HTML, you can ignore everything about
|
|
248
|
+
Puppeteer below — it is never loaded.
|
|
249
|
+
|
|
250
|
+
### What you need for PDFs
|
|
251
|
+
|
|
252
|
+
Puppeteer is an **optional peer dependency**: it is not installed with
|
|
253
|
+
`lifeastroapi`, and is imported only when you call a `*Pdf` function or `htmlToPdf`.
|
|
254
|
+
Pick one of these setups.
|
|
255
|
+
|
|
256
|
+
| Setup | Install | Disk | When to use |
|
|
257
|
+
|---|---|---|---|
|
|
258
|
+
| **Puppeteer** (simplest) | `npm install puppeteer` | roughly 400–500 MB — it downloads its own Chrome | A normal server, VM or container. |
|
|
259
|
+
| **puppeteer-core + your own Chrome** | `npm install puppeteer-core` | roughly 10–20 MB, plus the Chrome/Chromium you already have | Chrome is already on the machine, or you install it from your OS package manager. |
|
|
260
|
+
| **Serverless** | `npm install puppeteer-core @sparticuz/chromium` | sized to fit a Lambda layer | AWS Lambda, Vercel functions and similar. |
|
|
261
|
+
|
|
262
|
+
Also plan for:
|
|
263
|
+
|
|
264
|
+
- **Memory.** Each render runs a Chromium page; allow a few hundred MB of RAM for
|
|
265
|
+
the browser. Reuse one browser across requests rather than launching one per PDF
|
|
266
|
+
(see [Performance](#performance)).
|
|
267
|
+
- **Fonts.** See [Fonts](#fonts) — without the right fonts, Hindi and other Indic
|
|
268
|
+
text prints as empty boxes.
|
|
269
|
+
- **Puppeteer 24 or newer** is recommended. The page footer uses a CSS page-margin
|
|
270
|
+
box, which needs Chromium 131+; with an older browser the PDF still renders but
|
|
271
|
+
the footer line is not printed.
|
|
272
|
+
- **Not available** on runtimes that cannot run a browser (Cloudflare Workers, the
|
|
273
|
+
browser itself). Use the HTML layer there and convert elsewhere.
|
|
274
|
+
|
|
275
|
+
Calling a `*Pdf` function without Puppeteer installed throws a clear error telling
|
|
276
|
+
you to install it or pass your own.
|
|
277
|
+
|
|
278
|
+
### Quick start
|
|
279
|
+
|
|
280
|
+
```bash
|
|
281
|
+
npm install lifeastroapi puppeteer
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
```ts
|
|
285
|
+
import { LifeAstro } from "lifeastroapi";
|
|
286
|
+
import { kundliDetailedPdf } from "lifeastroapi/pdf";
|
|
287
|
+
import { writeFileSync } from "node:fs";
|
|
288
|
+
|
|
289
|
+
const client = new LifeAstro({ apiKey: process.env.LIFEASTRO_API_KEY });
|
|
290
|
+
|
|
291
|
+
// 1. Fetch the report JSON
|
|
292
|
+
const report = await client.reports.kundliDetailed({
|
|
293
|
+
date: "1990-01-15", time: "10:30", tz: "Asia/Kolkata", lat: 19.076, lon: 72.8777,
|
|
294
|
+
name: "Arjun Mehta", place: "Mumbai, India", lang: "hi",
|
|
295
|
+
});
|
|
296
|
+
|
|
297
|
+
// 2. Render a branded PDF in one call
|
|
298
|
+
const pdf = await kundliDetailedPdf(report, {
|
|
299
|
+
branding: {
|
|
300
|
+
companyName: "Acme Astro",
|
|
301
|
+
logoUrl: "https://cdn.acme.com/logo.png", // or a data: URI
|
|
302
|
+
primaryColor: "#6b21a8",
|
|
303
|
+
secondaryColor: "#9333ea",
|
|
304
|
+
footerText: "© Acme Astro — astrology for everyone",
|
|
305
|
+
watermarkText: "SAMPLE", // optional diagonal watermark
|
|
306
|
+
},
|
|
307
|
+
});
|
|
308
|
+
writeFileSync("kundli.pdf", pdf);
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
### Available reports
|
|
312
|
+
|
|
313
|
+
Each report has a `render*Html` and a `*Pdf` form:
|
|
314
|
+
|
|
315
|
+
| Report | API method | HTML | PDF |
|
|
316
|
+
|---|---|---|---|
|
|
317
|
+
| Kundli (lite) | `reports.kundliLite` | `renderKundliLiteHtml` | `kundliLitePdf` |
|
|
318
|
+
| Kundli (detailed) | `reports.kundliDetailed` | `renderKundliDetailedHtml` | `kundliDetailedPdf` |
|
|
319
|
+
| Brihad Kundli | `reports.kundliBrihad` | `renderKundliBrihadHtml` | `kundliBrihadPdf` |
|
|
320
|
+
| Match-making | `reports.matchMaking` | `renderMatchMakingHtml` | `matchMakingPdf` |
|
|
321
|
+
| Mangal Dosha | `reports.mangalDosha` | `renderMangalDoshaHtml` | `mangalDoshaPdf` |
|
|
322
|
+
| Dasha analysis | `reports.dashaAnalysis` | `renderDashaAnalysisHtml` | `dashaAnalysisPdf` |
|
|
323
|
+
| Numerology | `reports.numerology` | `renderNumerologyHtml` | `numerologyPdf` |
|
|
324
|
+
| Sade Sati | `reports.sadeSati` | `renderSadeSatiHtml` | `sadeSatiPdf` |
|
|
325
|
+
| Varshaphal | `reports.varshaphal` | `renderVarshaphalHtml` | `varshaphalPdf` |
|
|
326
|
+
| Horoscope (daily / weekly / monthly) | `reports.horoscopeDaily` … | `renderHoroscopeHtml` | `horoscopePdf` |
|
|
327
|
+
|
|
328
|
+
All render in `en`, `hi` and `mr` (and other locales where the report data carries
|
|
329
|
+
them) — pass `lang` when you request the report.
|
|
330
|
+
|
|
331
|
+
**Brihad Kundli** is the large one (well over 100 pages). `kundliBrihadPdf` renders
|
|
332
|
+
it twice so the table of contents shows real page numbers, adds a running header
|
|
333
|
+
and footer, and writes PDF bookmarks. It is the slowest report to produce — give it
|
|
334
|
+
a generous timeout and render it in a background job rather than inside a web
|
|
335
|
+
request. For exact page numbers in the table of contents, also install the optional
|
|
336
|
+
`pdfjs-dist` (`npm install pdfjs-dist`); without it the SDK falls back to an
|
|
337
|
+
estimate.
|
|
338
|
+
|
|
339
|
+
### Names and places on the cover
|
|
340
|
+
|
|
341
|
+
Pass `name` and `place` (or `boyName` / `girlName` / `boyPlace` / `girlPlace` for
|
|
342
|
+
match-making) when you request the report. Without them the cover reads "Subject" /
|
|
343
|
+
"Boy" / "Girl" and shows the birth coordinates.
|
|
344
|
+
|
|
345
|
+
```ts
|
|
346
|
+
const report = await client.reports.matchMaking({
|
|
347
|
+
boy, girl, boyName: "Arjun", girlName: "Asha", boyPlace: "Mumbai", girlPlace: "Delhi",
|
|
348
|
+
});
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
`place` is display text only — the chart is always computed from `lat` / `lon`.
|
|
352
|
+
|
|
353
|
+
### Branding
|
|
354
|
+
|
|
355
|
+
| Field | Effect |
|
|
356
|
+
|---|---|
|
|
357
|
+
| `companyName` | Shown on the cover. |
|
|
358
|
+
| `logoUrl` | Cover logo. `http(s)`, `data:image/...` or a relative URL. |
|
|
359
|
+
| `primaryColor` / `secondaryColor` | Headings, table headers, accents. |
|
|
360
|
+
| `footerText` | Line printed in the bottom margin of every page. |
|
|
361
|
+
| `watermarkText` | Optional diagonal watermark. |
|
|
362
|
+
|
|
363
|
+
**Precedence:** the `branding` you pass overrides the per-account branding embedded
|
|
364
|
+
in the report JSON, which falls back to neutral defaults.
|
|
365
|
+
|
|
366
|
+
### Performance
|
|
367
|
+
|
|
368
|
+
Launching Chromium for every PDF is slow. On a server, launch one browser and
|
|
369
|
+
reuse it — the SDK will not close a browser you pass in:
|
|
370
|
+
|
|
371
|
+
```ts
|
|
372
|
+
import puppeteer from "puppeteer";
|
|
373
|
+
const browser = await puppeteer.launch();
|
|
374
|
+
const pdf = await kundliDetailedPdf(report, { branding, browser });
|
|
375
|
+
// ... reuse `browser` for later requests; call browser.close() on shutdown
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
### Your own Chrome (`puppeteer-core`)
|
|
379
|
+
|
|
380
|
+
```ts
|
|
381
|
+
import puppeteer from "puppeteer-core";
|
|
382
|
+
const browser = await puppeteer.launch({
|
|
383
|
+
executablePath: "/usr/bin/chromium", // macOS: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
|
|
384
|
+
});
|
|
385
|
+
const pdf = await kundliLitePdf(report, { browser });
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
Or let the SDK launch it: `kundliLitePdf(report, { puppeteer, launchOptions: { executablePath } })`.
|
|
389
|
+
|
|
390
|
+
### Serverless (AWS Lambda and similar)
|
|
391
|
+
|
|
392
|
+
```ts
|
|
393
|
+
import chromium from "@sparticuz/chromium";
|
|
394
|
+
import puppeteer from "puppeteer-core";
|
|
395
|
+
const browser = await puppeteer.launch({
|
|
396
|
+
executablePath: await chromium.executablePath(),
|
|
397
|
+
args: chromium.args,
|
|
398
|
+
});
|
|
399
|
+
const pdf = await horoscopePdf(report, { browser });
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
Serverless Chromium images ship without Indic fonts — bundle the Noto fonts you
|
|
403
|
+
need with your function (see [Fonts](#fonts)).
|
|
404
|
+
|
|
405
|
+
### Docker / Linux servers
|
|
406
|
+
|
|
407
|
+
A minimal image that can render every report, including Hindi:
|
|
408
|
+
|
|
409
|
+
```dockerfile
|
|
410
|
+
FROM node:22-slim
|
|
411
|
+
RUN apt-get update && apt-get install -y --no-install-recommends \
|
|
412
|
+
chromium fonts-noto-core fonts-noto-extra \
|
|
413
|
+
&& rm -rf /var/lib/apt/lists/*
|
|
414
|
+
ENV PUPPETEER_SKIP_DOWNLOAD=true
|
|
415
|
+
WORKDIR /app
|
|
416
|
+
COPY package*.json ./
|
|
417
|
+
RUN npm ci
|
|
418
|
+
COPY . .
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
with `puppeteer.launch({ executablePath: "/usr/bin/chromium", args: ["--no-sandbox"] })`.
|
|
422
|
+
`--no-sandbox` is needed when the container runs as root; prefer running as a
|
|
423
|
+
non-root user and keeping the sandbox.
|
|
424
|
+
|
|
425
|
+
### Fonts
|
|
426
|
+
|
|
427
|
+
The templates ask for the Noto Sans families. Chromium does **not** bundle fonts, so
|
|
428
|
+
the machine that renders the PDF must have fonts covering the scripts you use.
|
|
429
|
+
Without them, Devanagari and other Indic text prints as empty boxes.
|
|
430
|
+
|
|
431
|
+
- Debian / Ubuntu: `apt install fonts-noto-core` (add `fonts-noto-extra` for the
|
|
432
|
+
full set of Indic scripts)
|
|
433
|
+
- macOS and Windows desktops already include Devanagari fonts.
|
|
434
|
+
|
|
435
|
+
### Without Puppeteer
|
|
436
|
+
|
|
437
|
+
Bring your own renderer, or run where a browser is not available — the HTML layer
|
|
438
|
+
has no dependencies:
|
|
439
|
+
|
|
440
|
+
```ts
|
|
441
|
+
import { renderMatchMakingHtml } from "lifeastroapi/pdf";
|
|
442
|
+
const html = renderMatchMakingHtml(matchReport, { primaryColor: "#b91c1c" });
|
|
443
|
+
// → your own Puppeteer/Playwright, Gotenberg, a print service, or the browser's Print dialog
|
|
444
|
+
```
|
|
445
|
+
|
|
446
|
+
The HTML is a complete, self-contained document with print CSS (A4, page margins,
|
|
447
|
+
footer), so any Chromium-based converter gives the same layout. The Brihad table of
|
|
448
|
+
contents, running header and bookmarks are added by `kundliBrihadPdf` and are not
|
|
449
|
+
part of the plain HTML.
|
|
450
|
+
|
|
451
|
+
### `htmlToPdf` options
|
|
452
|
+
|
|
453
|
+
All `*Pdf` functions accept these alongside `branding`:
|
|
454
|
+
|
|
455
|
+
| Option | Default | Meaning |
|
|
456
|
+
|---|---|---|
|
|
457
|
+
| `browser` | — | Reuse a launched browser. Not closed for you. |
|
|
458
|
+
| `puppeteer` | — | Inject the module (`puppeteer-core`). |
|
|
459
|
+
| `launchOptions` | — | Passed to `puppeteer.launch()` when the SDK launches the browser. |
|
|
460
|
+
| `format` | `"A4"` | `A3`, `A5`, `Letter`, `Legal`, `Tabloid`. |
|
|
461
|
+
| `landscape` | `false` | Landscape orientation. |
|
|
462
|
+
| `printBackground` | `true` | Print background colours. |
|
|
463
|
+
| `margin` | template's | `{ top, bottom, left, right }`, e.g. `"10mm"`. |
|
|
464
|
+
| `scale` | `1` | Render scale, 0.1–2. |
|
|
465
|
+
| `timeoutMs` | `30000` | Time allowed for the page to load. |
|
|
466
|
+
|
|
467
|
+
### Security
|
|
468
|
+
|
|
469
|
+
Branding inputs are sanitized — colours are validated against a safe allowlist, the
|
|
470
|
+
watermark and footer are CSS-escaped, and `logoUrl` is restricted to `http(s)`,
|
|
471
|
+
`data:image/...` and relative URLs. Chromium **fetches `logoUrl`** while rendering,
|
|
472
|
+
so if you ever pass a logo URL supplied by an end user, run Puppeteer with
|
|
473
|
+
restricted network egress to avoid requests to internal hosts (SSRF).
|
|
474
|
+
|
|
475
|
+
### Troubleshooting
|
|
476
|
+
|
|
477
|
+
| Symptom | Cause and fix |
|
|
478
|
+
|---|---|
|
|
479
|
+
| `PDF rendering requires Puppeteer` | Puppeteer is not installed. `npm install puppeteer`, or pass `{ puppeteer }` / `{ browser }`. |
|
|
480
|
+
| `Could not find Chrome` | `puppeteer-core` has no browser of its own — pass `executablePath`. With `puppeteer`, run `npx puppeteer browsers install chrome`. |
|
|
481
|
+
| Hindi text shows as boxes | No Indic font on the machine. Install Noto fonts (see [Fonts](#fonts)). |
|
|
482
|
+
| Browser fails to launch in Docker | Missing system libraries or the sandbox. Use the Dockerfile above. |
|
|
483
|
+
| No footer line on pages | The browser is older than Chromium 131. Update Puppeteer. |
|
|
484
|
+
| Timeouts on Brihad Kundli | It is a very large document rendered twice. Raise `timeoutMs` and render in a background job. |
|
|
485
|
+
| Cover says "Subject" | Pass `name` (and `place`) when requesting the report. |
|
|
486
|
+
|
|
487
|
+
## Contributing
|
|
488
|
+
|
|
489
|
+
The typed surface is generated from a manifest. After editing
|
|
490
|
+
`scripts/endpoints_part*.json`, regenerate and build:
|
|
491
|
+
|
|
492
|
+
```bash
|
|
493
|
+
npm run generate # regenerate src/resources/*
|
|
494
|
+
npm run typecheck
|
|
495
|
+
npm run build
|
|
496
|
+
npm test
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
Unit tests use a fake `fetch`, so they cannot tell whether the API really accepts a
|
|
500
|
+
parameter. `npm run live` calls **every** method against a real server and lists each
|
|
501
|
+
one the API rejects:
|
|
502
|
+
|
|
503
|
+
```bash
|
|
504
|
+
npm run build
|
|
505
|
+
LIFEASTRO_API_KEY=dv_live_... npm run live # skips /v1/reports/ (500–8000 credits each)
|
|
506
|
+
LIFEASTRO_API_KEY=dv_live_... LIFEASTRO_LIVE_SKIP="" npm run live # include reports
|
|
507
|
+
LIFEASTRO_API_URL=http://localhost:8080 ... npm run live # sweep a local server instead
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
It spends credits (one request per endpoint).
|
|
511
|
+
|
|
512
|
+
## License
|
|
513
|
+
|
|
514
|
+
MIT © Ayanshu Life
|