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 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
- # Temporary Holding Version
1
+ # lifeastroapi
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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