lifeastroapi 0.9.1 → 0.13.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
@@ -5,7 +5,7 @@ Official **Node.js / TypeScript SDK** for [LifeAstroAPI](https://lifeastroapi.co
5
5
  kundli, muhurat and Western charts, with location-aware calculations and pay-per-call billing.
6
6
  Free tier: 1,500 credits a month, no card — [get a key](https://lifeastroapi.com/signup/).
7
7
 
8
- - ✅ **All 321 endpoints**, fully typed, across 23 namespaces — panchang, charts, dashas,
8
+ - ✅ **All 322 endpoints**, fully typed, across 23 namespaces — panchang, charts, dashas,
9
9
  matchmaking, transits, horoscopes, numerology, tarot, muhurta, reports, narratives,
10
10
  and a complete Western (tropical) module.
11
11
  - ✅ **Zero runtime dependencies** — uses the platform `fetch` (Node 18+, Bun, Deno,
@@ -206,7 +206,7 @@ const chart = await client.chart.planets({
206
206
  | Namespace | What it covers |
207
207
  |-----------|----------------|
208
208
  | `panchang` | tithi, nakshatra, yoga, karana, vara, sunrise/sunset, rahu-kaal, choghadiya, hora, muhurtas, monthly calendar, composite `basic`/`advanced` |
209
- | `chart` | planets, ascendant, houses, divisional (D1–D60), dignity, aspects, shadbala, ashtakvarga, avakhada, KP, astro-details; data bundles `kundliFacts`, `yogas`, `doshas`, birth-time `sensitivity` |
209
+ | `chart` | planets, ascendant, houses, divisional (D1–D60), dignity, aspects, shadbala, ashtakvarga, avakhada, KP (sub lords, ruling planets, significators, 4-step chain), astro-details; data bundles `kundliFacts`, `yogas`, `doshas`, birth-time `sensitivity` |
210
210
  | `dasha` | full + current Vimshottari (5-level drill-down) and Yogini |
211
211
  | `milan` | Ashtakoota (total / full / per-koota), mangal/nadi/shani dosha, navamsa & dasha compatibility (`dashaSync` with an aligned MD/AD `timeline` and `marriageWindows`), chart `overlay`, one-call `summary` |
212
212
  | `transit` | positions, sade-sati, ashtakavarga, tarabala, vedha, double-transit, small-panoti; dated `sadeSatiWindows` and per-planet sign `windows` |
@@ -214,7 +214,7 @@ const chart = await client.chart.planets({
214
214
  | `numerology` | driver, conductor, soul, personality, destiny, full, advanced, challenges, personalPeriods |
215
215
  | `muhurta` | vivah, naamkaran, griha-pravesh, vyapar, yatra, best-time, … |
216
216
  | `varshaphal` | annual chart, lord, muntha, mudda-dasha, harsha-bala, tajika yogas |
217
- | `prashna` | horary answer, chart, arudha, significators |
217
+ | `prashna` | horary answer, chart, arudha, significators, KP horary (1–249) |
218
218
  | `eclipses` | solar / lunar / all (date range, optional visibility) |
219
219
  | `calendar` | Hindu month, ritu, samvatsara, adhik-maas |
220
220
  | `festivals` | full Hindu festival calendar by month / on a date — location-aware, `lang`, `monthSystem` (amanta/purnimanta); `panchang.monthly({ include: "sheet" })` returns a complete printable calendar page |
@@ -298,6 +298,38 @@ const controller = new AbortController();
298
298
  await client.chart.planets(birth, { signal: controller.signal, timeoutMs: 5000 });
299
299
  ```
300
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
+
301
333
  ## Branded PDF reports
302
334
 
303
335
  The `lifeastroapi/pdf` subpath turns the JSON from `client.reports.*` into
@@ -562,6 +594,15 @@ restricted network egress to avoid requests to internal hosts (SSRF).
562
594
 
563
595
  ## React Native and Expo
564
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
+
565
606
  The SDK runs in React Native as it does in Node: the client uses the platform `fetch`,
566
607
  and `lifeastroapi/pdf-html` builds the report HTML with no Puppeteer and no Node code.
567
608
  The device's own print engine turns that HTML into a PDF, so the report is rendered on
package/dist/index.cjs CHANGED
@@ -102,6 +102,40 @@ function httpStatusCode(status) {
102
102
  }
103
103
 
104
104
  // src/http.ts
105
+ function responseInfo(res, path) {
106
+ const h = res.headers;
107
+ const num = (name) => {
108
+ const v = h.get(name);
109
+ if (v === null || v.trim() === "") return void 0;
110
+ const n = Number(v);
111
+ return Number.isFinite(n) ? n : void 0;
112
+ };
113
+ const info = { status: res.status, path };
114
+ const rid = h.get("x-request-id");
115
+ if (rid) info.requestId = rid;
116
+ const credits = num("x-credits-remaining");
117
+ if (credits !== void 0) info.creditsRemaining = credits;
118
+ const limit = num("x-ratelimit-limit");
119
+ const remaining = num("x-ratelimit-remaining");
120
+ const reset = num("x-ratelimit-reset");
121
+ if (limit !== void 0 && remaining !== void 0 && reset !== void 0) {
122
+ info.rateLimit = { limit, remaining, resetAt: new Date(reset * 1e3) };
123
+ }
124
+ const cache = h.get("x-cache");
125
+ if (cache) info.cache = cache;
126
+ const lang = h.get("content-language");
127
+ if (lang) info.language = lang;
128
+ return info;
129
+ }
130
+ function emit(hooks, info) {
131
+ for (const hook of hooks) {
132
+ if (!hook) continue;
133
+ try {
134
+ hook(info);
135
+ } catch {
136
+ }
137
+ }
138
+ }
105
139
  var RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 425, 429, 500, 502, 503, 504]);
106
140
  function encodeQuery(params) {
107
141
  const usp = new URLSearchParams();
@@ -203,6 +237,7 @@ async function performRequest(config, path, query, opts = {}) {
203
237
  body = text;
204
238
  }
205
239
  if (res.ok) {
240
+ emit([config.onResponse, opts.onResponse], responseInfo(res, path));
206
241
  if (opts.raw) return body;
207
242
  const envelope = body;
208
243
  if (envelope && typeof envelope === "object" && "data" in envelope) {
@@ -216,6 +251,7 @@ async function performRequest(config, path, query, opts = {}) {
216
251
  await sleep(backoffMs(attempt, retryAfter), opts.signal);
217
252
  continue;
218
253
  }
254
+ emit([config.onResponse, opts.onResponse], responseInfo(res, path));
219
255
  throw lastError;
220
256
  }
221
257
  throw lastError ?? new LifeAstroConnectionError("Request failed after retries");
@@ -528,11 +564,11 @@ var Chart = class {
528
564
  houses(input, opts) {
529
565
  return this._c.request("/v1/chart/houses", applyExtras(qBirth(input), input, [["lang", "lang"], ["lang", "locale"]]), opts);
530
566
  }
531
- /** Get KP (Krishnamurti Paddhati) house significators for a given cusp — lists planets that significate the house through occupancy, lordship, and sub-lord chain. */
567
+ /** KP house significators for all 12 Placidus cusps (20 credits): each cusp's star, sub and sub-sub lords and its significator planets (four KP levels), the houses every planet signifies, and the KP 4-step chain. Pass ayanamsa krishnamurti for KP work. `cusp` is accepted for compatibility and ignored: all 12 cusps are returned. */
532
568
  kpHouseSignificator(input, opts) {
533
569
  return this._c.request("/v1/chart/kp-house-significator", applyExtras(qBirth(input), input, [["cusp", "cusp"], ["lang", "lang"], ["lang", "locale"]]), opts);
534
570
  }
535
- /** Get the KP sublord of a planet — the sub-lord of the nakshatra sub-division the planet occupies (KP star lord → sub lord → sub-sub lord chain). */
571
+ /** KP star, sub and sub-sub lords of every planet (10 credits), and the KP ruling planets for the moment and place (day lord, and the star, sign and sub lords of the ascendant and the Moon); send the moment of judgement for horary or timing. Pass ayanamsa krishnamurti for KP work. `planet` is accepted for compatibility and ignored: all planets are returned. */
536
572
  kpSublord(input, opts) {
537
573
  return this._c.request("/v1/chart/kp-sublord", applyExtras(qBirth(input), input, [["planet", "planet"], ["lang", "lang"], ["lang", "locale"]]), opts);
538
574
  }
@@ -1262,6 +1298,10 @@ var Prashna = class {
1262
1298
  chart(input, opts) {
1263
1299
  return this._c.request("/v1/prashna/chart", applyExtras(qMoment(input), input, [["lang", "lang"], ["lang", "locale"]]), opts);
1264
1300
  }
1301
+ /** KP horary chart for a number from 1 to 249 (30 credits), cast for the moment and place of judgement: the horary ascendant (the first degree of that number's sign/star/sub part), the 12 Placidus cusps with star, sub and sub-sub lords and significators, planets with KP lords and houses, planet significators, the 4-step chain and the ruling planets of the moment. Uses the Krishnamurti ayanamsa unless ayanamsa is sent. */
1302
+ kpHorary(input, opts) {
1303
+ return this._c.request("/v1/prashna/kp-horary", applyExtras(qMoment(input), input, [["number", "number"], ["lang", "lang"], ["lang", "locale"]]), opts);
1304
+ }
1265
1305
  /** Get the lagna lord analysis for a Prashna chart — where the lagna lord is placed, its strength, and what it indicates about the querent's situation and chances of success. */
1266
1306
  lagnaLord(input, opts) {
1267
1307
  return this._c.request("/v1/prashna/lagna-lord", applyExtras(qMoment(input), input, [["lang", "lang"], ["lang", "locale"]]), opts);
@@ -2012,7 +2052,7 @@ var Resources = class {
2012
2052
  };
2013
2053
 
2014
2054
  // src/client.ts
2015
- var VERSION = "0.9.1";
2055
+ var VERSION = "0.13.0";
2016
2056
  var DEFAULT_BASE_URL = "https://api.lifeastroapi.com";
2017
2057
  function resolveConfig(options) {
2018
2058
  const opts = typeof options === "string" ? { apiKey: options } : options ?? {};
@@ -2036,7 +2076,8 @@ function resolveConfig(options) {
2036
2076
  maxRetries: Math.max(0, opts.maxRetries ?? 2),
2037
2077
  fetch: fetchImpl,
2038
2078
  userAgent: `lifeastroapi-node/${VERSION}`,
2039
- defaultHeaders: opts.defaultHeaders ?? {}
2079
+ defaultHeaders: opts.defaultHeaders ?? {},
2080
+ onResponse: opts.onResponse
2040
2081
  };
2041
2082
  }
2042
2083
  var LifeAstro = class extends Resources {