lifeastroapi 0.9.0 → 0.12.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/README.md CHANGED
@@ -17,6 +17,8 @@ Free tier: 1,500 credits a month, no card — [get a key](https://lifeastroapi.c
17
17
  print-ready kundli / matchmaking / numerology / horoscope PDFs. Rendering needs
18
18
  Puppeteer (a headless Chrome), installed separately — see
19
19
  [Branded PDF reports](#branded-pdf-reports).
20
+ - ✅ **React Native and Expo**: the same client, and report PDFs printed on the
21
+ device from `lifeastroapi/pdf-html` — see [React Native and Expo](#react-native-and-expo).
20
22
 
21
23
  ```bash
22
24
  npm install lifeastroapi
@@ -83,8 +85,9 @@ error. Get a key at **https://lifeastroapi.com/dashboard/keys**.
83
85
  > desktop, or any client-side code**, where end users could extract it and run up your bill.
84
86
  > For client apps, call LifeAstroAPI from your own backend and forward the results.
85
87
  >
86
- > (Need PDFs in the browser? The dependency-free `lifeastroapi/pdf` `render*Html`
87
- > functions take **no key** and are safe to run anywhere — see [Branded PDF reports](#branded-pdf-reports).)
88
+ > (Need PDFs in a browser or a mobile app? The dependency-free `render*Html` functions of
89
+ > `lifeastroapi/pdf-html` take **no key** and are safe to run anywhere — see
90
+ > [React Native and Expo](#react-native-and-expo).)
88
91
 
89
92
  ## Configuration
90
93
 
@@ -295,6 +298,38 @@ const controller = new AbortController();
295
298
  await client.chart.planets(birth, { signal: controller.signal, timeoutMs: 5000 });
296
299
  ```
297
300
 
301
+ ## Credits, rate limit and request id
302
+
303
+ Every response carries your credit balance, your plan's rate limit and a request id in its
304
+ headers. `onResponse` hands them to you, for every call (client option) or for one call:
305
+
306
+ ```ts
307
+ const client = new LifeAstro({
308
+ onResponse: (info) => {
309
+ if (info.creditsRemaining !== undefined && info.creditsRemaining < 5_000) {
310
+ console.warn(`LifeAstroAPI credits low: ${info.creditsRemaining}`);
311
+ }
312
+ },
313
+ });
314
+
315
+ await client.panchang.basic({ lat: 19.076, lon: 72.8777, tz: "Asia/Kolkata" }, {
316
+ onResponse: (info) => console.log(info.requestId, info.rateLimit?.remaining),
317
+ });
318
+ ```
319
+
320
+ | Field | From header | Meaning |
321
+ |---|---|---|
322
+ | `status` | | HTTP status |
323
+ | `path` | | Endpoint path, e.g. `/v1/panchang/basic` |
324
+ | `requestId` | `X-Request-ID` | Quote it to support |
325
+ | `creditsRemaining` | `X-Credits-Remaining` | Balance after the call; unchanged after a failed call (failed calls are free). Absent on the free tier, whose allowance is daily/monthly rather than a balance |
326
+ | `rateLimit` | `X-RateLimit-*` | `{ limit, remaining, resetAt }` per minute for your plan |
327
+ | `cache` | `X-Cache` | `HIT` when the API answered from its cache (billed the same) |
328
+ | `language` | `Content-Language` | Language of the answer |
329
+
330
+ The hook runs once per call with the final response, success or error (not for retried attempts
331
+ or network failures). An exception thrown inside it is ignored, so logging can never break a call.
332
+
298
333
  ## Branded PDF reports
299
334
 
300
335
  The `lifeastroapi/pdf` subpath turns the JSON from `client.reports.*` into
@@ -508,7 +543,7 @@ Bring your own renderer, or run where a browser is not available — the HTML la
508
543
  has no dependencies:
509
544
 
510
545
  ```ts
511
- import { renderMatchMakingHtml } from "lifeastroapi/pdf";
546
+ import { renderMatchMakingHtml } from "lifeastroapi/pdf-html"; // or "lifeastroapi/pdf"
512
547
  const html = renderMatchMakingHtml(matchReport, { primaryColor: "#b91c1c" });
513
548
  // → your own Puppeteer/Playwright, Gotenberg, a print service, or the browser's Print dialog
514
549
  ```
@@ -518,6 +553,9 @@ footer), so any Chromium-based converter gives the same layout. The Brihad table
518
553
  contents, running header and bookmarks are added by `kundliBrihadPdf` and are not
519
554
  part of the plain HTML.
520
555
 
556
+ `lifeastroapi/pdf-html` has only the HTML renderers and branding helpers: no Puppeteer
557
+ and no Node code, so it bundles for browsers, edge runtimes and React Native.
558
+
521
559
  ### `htmlToPdf` options
522
560
 
523
561
  All `*Pdf` functions accept these alongside `branding`:
@@ -554,6 +592,88 @@ restricted network egress to avoid requests to internal hosts (SSRF).
554
592
  | Timeouts on Brihad Kundli | It is a very large document rendered twice. Raise `timeoutMs` and render in a background job. |
555
593
  | Cover says "Subject" | Pass `name` (and `place`) when requesting the report. |
556
594
 
595
+ ## React Native and Expo
596
+
597
+ **A working starter** (Expo app + the small backend that holds the key) is in
598
+ [`examples/react-native-expo`](examples/react-native-expo).
599
+
600
+ | Part | Node.js (server) | React Native / Expo | Browser |
601
+ |---|---|---|---|
602
+ | `lifeastroapi` client (all methods, `lang`, retries, errors, `onResponse`) | yes | yes, but call it from your backend so the key stays secret | yes, same caveat |
603
+ | `lifeastroapi/pdf-html` (report HTML, `A4_PRINT_OPTIONS`) | yes | yes; print with `expo-print` | yes; print with the browser |
604
+ | `lifeastroapi/pdf` (Puppeteer PDFs, Brihad table of contents and bookmarks) | yes | no | no |
605
+
606
+ The SDK runs in React Native as it does in Node: the client uses the platform `fetch`,
607
+ and `lifeastroapi/pdf-html` builds the report HTML with no Puppeteer and no Node code.
608
+ The device's own print engine turns that HTML into a PDF, so the report is rendered on
609
+ the phone.
610
+
611
+ ```bash
612
+ npm install lifeastroapi
613
+ npx expo install expo-print expo-sharing
614
+ ```
615
+
616
+ ```tsx
617
+ import * as Print from "expo-print";
618
+ import * as Sharing from "expo-sharing";
619
+ import { renderKundliLiteHtml, A4_PRINT_OPTIONS } from "lifeastroapi/pdf-html";
620
+
621
+ // 1. Report JSON from YOUR backend (see below); it is the JSON of client.reports.kundliLite().
622
+ const report = await (await fetch("https://api.your-app.example/kundli?lang=bn")).json();
623
+
624
+ // 2. Branded HTML, built on the device
625
+ const html = renderKundliLiteHtml(report, {
626
+ companyName: "Acme Astro",
627
+ primaryColor: "#6b21a8",
628
+ });
629
+
630
+ // 3. PDF, printed on the device
631
+ const { uri } = await Print.printToFileAsync({ html, ...A4_PRINT_OPTIONS });
632
+ await Sharing.shareAsync(uri, { mimeType: "application/pdf" });
633
+ ```
634
+
635
+ **Keep the API key on your server.** Anything shipped inside an app can be read out of
636
+ it. Call LifeAstroAPI from your backend with this SDK and send the JSON to the app:
637
+
638
+ ```ts
639
+ // your backend (Node)
640
+ import { LifeAstro } from "lifeastroapi";
641
+ const client = new LifeAstro(); // reads LIFEASTRO_API_KEY
642
+
643
+ app.get("/kundli", async (req, res) => {
644
+ res.json(await client.reports.kundliLite({ ...birthOf(req.user), lang: req.query.lang }));
645
+ });
646
+ ```
647
+
648
+ What to know:
649
+
650
+ - **Entry point.** Import the renderers from `lifeastroapi/pdf-html` in an app.
651
+ `lifeastroapi/pdf` also carries the Puppeteer `*Pdf` functions, which cannot run on a
652
+ phone. Metro finds the subpath through the package `exports` field, which is on by
653
+ default from React Native 0.79 (Expo SDK 53).
654
+ - **Page size and margins.** The templates set A4 and the page margins with a CSS `@page`
655
+ rule. Chromium follows it; the iOS print engine does not, so pass `A4_PRINT_OPTIONS`
656
+ (`width`, `height` and `margins` in points) to `printToFileAsync`.
657
+ - **All ten reports** have a renderer: `renderKundliLiteHtml`, `renderKundliDetailedHtml`,
658
+ `renderKundliBrihadHtml`, `renderMatchMakingHtml`, `renderMangalDoshaHtml`,
659
+ `renderDashaAnalysisHtml`, `renderNumerologyHtml`, `renderSadeSatiHtml`,
660
+ `renderVarshaphalHtml` and `renderHoroscopeHtml`, in every language the PDF reports
661
+ support.
662
+ - **Differences from the Puppeteer PDF.** The footer line and the Brihad Kundli table of
663
+ contents, running header and bookmarks are drawn by Chromium features, so they are not
664
+ in a device-printed PDF. If you need them, make that PDF on your server with
665
+ `lifeastroapi/pdf` and download it in the app.
666
+ - **Fonts.** iOS and Android include fonts for the Indian scripts. The templates also name
667
+ the Noto fonts, which the device uses when they are installed.
668
+ - **Timeouts and errors** are the same classes as in Node (`AuthenticationError`,
669
+ `RateLimitError`, `LifeAstroConnectionError` with `code: "timeout"` …).
670
+
671
+ Tested in an Expo SDK 58 app (React Native 0.88) on the iOS simulator: client calls with
672
+ `lang`, typed errors, and Kundli (Bengali), detailed Kundli (Hindi) and match-making
673
+ (Tamil) PDFs. An Android build bundles; it has not been run on an Android device.
674
+ Without Expo, any library that prints HTML to PDF with the system WebView takes the same
675
+ HTML.
676
+
557
677
  ## Contributing
558
678
 
559
679
  The typed surface is generated from a manifest. After editing