kaabalah 5.2.0 → 5.4.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
@@ -20,6 +20,8 @@ Complete documentation here [https://docs.kaabalah.com/](https://docs.kaabalah.c
20
20
  npm install kaabalah
21
21
  ```
22
22
 
23
+ Node.js 18.18+ is required for the bundled CLI and runtime helpers.
24
+
23
25
  ## Support us on Ko-Fi
24
26
 
25
27
  If you find this package useful, you can support it on Ko-Fi too (or just star the repo):
@@ -117,10 +119,10 @@ kaabalah astrology 1990-01-15 14:30 --lat=40.7128 --lon=-74.006
117
119
  kaabalah astrology 1990-01-15 14:30 --location="New York, USA"
118
120
 
119
121
  # Synastry (cross-chart aspects)
120
- kaabalah astrology:synastry --input-json='{"chartA":{"date":"2001-10-02","time":"19:45","lat":-22.74,"lon":-47.33,"timezone":"America/Sao_Paulo"},"chartB":{"date":"1999-02-01","time":"14:30","lat":-23.96,"lon":-46.33,"timezone":"America/Sao_Paulo"}}' --json
122
+ kaabalah astrology:synastry --input-json=- --json < synastry.json
121
123
 
122
124
  # Composite (midpoint chart)
123
- kaabalah astrology:composite --input-json='{"chartA":{"date":"2001-10-02","time":"19:45","lat":-22.74,"lon":-47.33},"chartB":{"date":"1999-02-01","time":"14:30","lat":-23.96,"lon":-46.33}}' --json
125
+ kaabalah astrology:composite --input-json=- --json < composite.json
124
126
 
125
127
  # Tree of Life correspondences
126
128
  kaabalah tree:node path:1 --json
@@ -136,7 +138,9 @@ kaabalah tree:node sphere:Kether --type=tarotArkAnnu --json
136
138
  | `--no-json` | Force human-readable output even when piped |
137
139
  | `--compact` | Minified JSON (no indentation) |
138
140
  | `--fields=a.b,c.d` | Filter JSON output to specified dot-paths |
139
- | `--input-json='{"key":"val"}'` | Pass all parameters as a JSON object |
141
+ | `--input-json=-` | Read a JSON object from stdin |
142
+ | `--debug` | Emit debug logs to stderr (same effect as `DEBUG=kaabalah:*`) |
143
+ | `--trace` | Print stack traces for unexpected fatal errors in human-readable mode |
140
144
 
141
145
  ### Schema Introspection
142
146
 
@@ -148,6 +152,19 @@ kaabalah help --json
148
152
  kaabalah help astrology --json
149
153
  ```
150
154
 
155
+ ### Debugging
156
+
157
+ ```bash
158
+ # Emit parser/config/astrology debug logs to stderr
159
+ DEBUG=kaabalah:* kaabalah help --json
160
+
161
+ # Same as above, but from the CLI flag
162
+ kaabalah astrology 1990-01-15 14:30 --lat=40.7128 --lon=-74.006 --debug
163
+
164
+ # Add --trace while reproducing an unexpected fatal error locally
165
+ kaabalah <command> --trace --no-json
166
+ ```
167
+
151
168
  ## Development
152
169
 
153
170
  This project uses TypeScript and WebAssembly for the Swiss Ephemeris calculations.
@@ -148,11 +148,142 @@ declare function computeSynastryAspects(planetsA: Record<string, {
148
148
  }>, planetsB: Record<string, {
149
149
  longitude: number;
150
150
  }>, specs?: AspectSpec[]): AspectEdge[];
151
+ /** Shorter-arc midpoint of two ecliptic longitudes. */
152
+ declare function shorterArcMidpoint(a: number, b: number): number;
151
153
  declare function computeMidpoints(planetsA: Record<string, {
152
154
  longitude: number;
153
155
  }>, planetsB: Record<string, {
154
156
  longitude: number;
155
157
  }>): Record<string, number>;
158
+ interface TransitAspectEdge extends AspectEdge {
159
+ applying: boolean;
160
+ retrograde: boolean;
161
+ category: "slow" | "fast";
162
+ }
163
+ interface TransitAspectPoint {
164
+ longitude: number;
165
+ longitudeSpeed?: number;
166
+ }
167
+ declare const SLOW_PLANETS: Set<string>;
168
+ /**
169
+ * Compute transit-to-natal aspects with applying/separating, retrograde, and speed category.
170
+ *
171
+ * planetA = transit planet, planetB = natal planet/point.
172
+ */
173
+ declare function computeTransitAspects(transitPlanets: Record<string, TransitAspectPoint>, natalPlanets: Record<string, TransitAspectPoint>, specs?: AspectSpec[]): TransitAspectEdge[];
174
+
175
+ /**
176
+ * Essential Dignity Table — Traditional Hellenistic rulership data.
177
+ * Pure math, no WASM dependency.
178
+ */
179
+
180
+ type Sign = (typeof SIGNS)[number];
181
+ type TraditionalPlanet = "Sun" | "Moon" | "Mercury" | "Venus" | "Mars" | "Jupiter" | "Saturn";
182
+ interface EssentialDignityResult {
183
+ domicile: boolean;
184
+ exaltation: boolean;
185
+ detriment: boolean;
186
+ fall: boolean;
187
+ domicileRuler: TraditionalPlanet;
188
+ peregrine: boolean;
189
+ }
190
+ declare const DOMICILE_RULERS: Record<Sign, TraditionalPlanet>;
191
+ declare const EXALTATIONS: Record<TraditionalPlanet, {
192
+ sign: Sign;
193
+ degree: number;
194
+ }>;
195
+ declare function getDomicileRuler(sign: Sign): TraditionalPlanet;
196
+ declare function getExaltation(planet: TraditionalPlanet): {
197
+ sign: Sign;
198
+ degree: number;
199
+ };
200
+ declare function getOppositeSign(sign: Sign): Sign;
201
+ /** Signs where the planet is in detriment (opposite of its domicile signs). */
202
+ declare function getDetriment(planet: TraditionalPlanet): Sign[];
203
+ /** Sign where the planet is in fall (opposite of its exaltation sign). */
204
+ declare function getFall(planet: TraditionalPlanet): Sign;
205
+ declare function getEssentialDignity(planet: TraditionalPlanet, sign: Sign): EssentialDignityResult;
206
+
207
+ /**
208
+ * Decan (face) lookup — Chaldean rulers + Golden Dawn tarot correspondence.
209
+ * Pure math, no WASM dependency.
210
+ */
211
+
212
+ interface DecanResult {
213
+ sign: string;
214
+ decanNumber: 1 | 2 | 3;
215
+ ruler: TraditionalPlanet;
216
+ tarotCard: string;
217
+ startDegree: number;
218
+ endDegree: number;
219
+ degreeWithinSign: number;
220
+ }
221
+ declare function getDecan(longitude: number): DecanResult;
222
+
223
+ /**
224
+ * Dodecatemoria (12th parts) — traditional Hellenistic technique.
225
+ * Pure math, no WASM dependency.
226
+ */
227
+ interface DodecatemoriaResult {
228
+ originalSign: string;
229
+ originalDegree: number;
230
+ dodecatemoriaSign: string;
231
+ dodecatemoriaIndex: number;
232
+ }
233
+ declare function getDodecatemoria(longitude: number): DodecatemoriaResult;
234
+
235
+ /**
236
+ * Annual & Monthly Profections — traditional Hellenistic time-lord technique.
237
+ * Pure math. Requires a whole-sign BirthChart for house sign lookup.
238
+ */
239
+
240
+ interface AnnualProfection {
241
+ age: number;
242
+ house: number;
243
+ sign: string;
244
+ ruler: TraditionalPlanet;
245
+ targetYear: number;
246
+ }
247
+ interface MonthlyProfection {
248
+ month: number;
249
+ startDate: Date;
250
+ sign: string;
251
+ ruler: TraditionalPlanet;
252
+ }
253
+ interface MonthlyProfectionsResult {
254
+ annualProfection: AnnualProfection;
255
+ months: MonthlyProfection[];
256
+ }
257
+ declare function getAnnualProfection(natalChart: BirthChart, birthDate: Date, targetYear?: number): AnnualProfection;
258
+ declare function getMonthlyProfections(natalChart: BirthChart, birthDate: Date, targetYear?: number): MonthlyProfectionsResult;
259
+
260
+ /**
261
+ * Firdaria — traditional planetary period system.
262
+ * Pure math, no WASM dependency.
263
+ */
264
+ type FirdariaPlanet = "Sun" | "Moon" | "Mercury" | "Venus" | "Mars" | "Jupiter" | "Saturn" | "NorthNode" | "SouthNode";
265
+ interface FirdariaSubPeriod {
266
+ planet: FirdariaPlanet;
267
+ startDate: Date;
268
+ endDate: Date;
269
+ }
270
+ interface FirdariaMajorPeriod {
271
+ planet: FirdariaPlanet;
272
+ years: number;
273
+ startDate: Date;
274
+ endDate: Date;
275
+ subPeriods: FirdariaSubPeriod[];
276
+ }
277
+ interface FirdariaResult {
278
+ sect: "diurnal" | "nocturnal";
279
+ currentMajor: FirdariaMajorPeriod;
280
+ currentSub: FirdariaSubPeriod;
281
+ allPeriods: FirdariaMajorPeriod[];
282
+ }
283
+ interface FirdariaOptions {
284
+ nodeSubPeriodStart?: "jupiter-saturn" | "sun-mars";
285
+ }
286
+ declare function getFirdaria(birthDate: Date, isDiurnal: boolean, targetDate?: Date, options?: FirdariaOptions): FirdariaResult;
156
287
 
157
288
  /**
158
289
  * Astrological calculations using Swiss Ephemeris
@@ -202,6 +333,7 @@ interface BirthChart {
202
333
  };
203
334
  };
204
335
  aspects: AspectEdge[];
336
+ sect: "diurnal" | "nocturnal";
205
337
  }
206
338
  /**
207
339
  * Calculate a birth chart using Swiss Ephemeris
@@ -226,22 +358,18 @@ declare function formatDegreeMinutes(decimalDegrees: number): string;
226
358
  */
227
359
  declare function getZodiacPosition(longitude: number, houseCusps: number[]): ZodiacPosition;
228
360
  declare function findHouseOf(longitude: number, housePositions: number[]): number;
229
- interface SynastryChartOptions {
361
+ interface TwoChartOptions {
230
362
  chartA: BirthChartOptions;
231
363
  chartB: BirthChartOptions;
232
364
  aspectSpecs?: AspectSpec[];
233
365
  }
366
+ type SynastryChartOptions = TwoChartOptions;
367
+ type CompositeChartOptions = TwoChartOptions;
234
368
  interface SynastryChart {
235
369
  chartA: BirthChart;
236
370
  chartB: BirthChart;
237
371
  aspects: AspectEdge[];
238
372
  }
239
- declare function getSynastryChart(options: SynastryChartOptions): Promise<SynastryChart>;
240
- interface CompositeChartOptions {
241
- chartA: BirthChartOptions;
242
- chartB: BirthChartOptions;
243
- aspectSpecs?: AspectSpec[];
244
- }
245
373
  interface CompositeChart {
246
374
  chartA: BirthChart;
247
375
  chartB: BirthChart;
@@ -253,6 +381,70 @@ interface CompositeChart {
253
381
  compositeHouses: ZodiacPosition[];
254
382
  aspects: AspectEdge[];
255
383
  }
384
+ declare function getSynastryChart(options: SynastryChartOptions): Promise<SynastryChart>;
256
385
  declare function getCompositeChart(options: CompositeChartOptions): Promise<CompositeChart>;
386
+ interface TransitChartOptions {
387
+ natal: BirthChartOptions;
388
+ transitDate: Date;
389
+ transitLatitude?: number;
390
+ transitLongitude?: number;
391
+ transitTimeZoneSettings?: TimeZoneOptions;
392
+ aspectSpecs?: AspectSpec[];
393
+ maxOrb?: number;
394
+ transitPlanets?: string[];
395
+ natalPlanets?: string[];
396
+ aspectFilter?: AspectName[];
397
+ }
398
+ interface TransitPlanet extends HydratedPlanet {
399
+ retrograde: boolean;
400
+ natalHouse: number;
401
+ }
402
+ interface TransitChart {
403
+ natalChart: BirthChart;
404
+ transitDateUtc: Date;
405
+ transitPlanets: Record<string, TransitPlanet>;
406
+ aspects: TransitAspectEdge[];
407
+ }
408
+ interface TransitRangeOptions extends Omit<TransitChartOptions, "transitDate"> {
409
+ from: Date;
410
+ to: Date;
411
+ stepDays?: number;
412
+ }
413
+ interface AspectPerfection {
414
+ transitPlanet: string;
415
+ natalPlanet: string;
416
+ aspect: AspectName;
417
+ exactDate: Date;
418
+ exactOrb: number;
419
+ retrograde: boolean;
420
+ category: "slow" | "fast";
421
+ }
422
+ interface TransitRangeResult {
423
+ natalChart: BirthChart;
424
+ from: Date;
425
+ to: Date;
426
+ perfections: AspectPerfection[];
427
+ }
428
+ declare function getTransitChart(options: TransitChartOptions): Promise<TransitChart>;
429
+ declare function getTransitRange(options: TransitRangeOptions): Promise<TransitRangeResult>;
430
+ interface SolarReturnOptions {
431
+ natal: BirthChartOptions;
432
+ year: number;
433
+ solarReturnLatitude?: number;
434
+ solarReturnLongitude?: number;
435
+ solarReturnHouseSystem?: HouseSystem;
436
+ }
437
+ interface SolarReturnChart {
438
+ natalChart: BirthChart;
439
+ solarReturnChart: BirthChart;
440
+ exactReturnDate: Date;
441
+ natalSunLongitude: number;
442
+ year: number;
443
+ }
444
+ /**
445
+ * Calculate a Solar Return chart — the moment the transiting Sun returns
446
+ * to its natal longitude in the given year.
447
+ */
448
+ declare function getSolarReturnChart(options: SolarReturnOptions): Promise<SolarReturnChart>;
257
449
 
258
- export { type AspectEdge, type AspectName, type AspectSpec, type BirthChart, type BirthChartOptions, CalcFlag, type CompositeChart, type CompositeChartOptions, DEFAULT_ASPECT_SPECS, HouseSystem, type HydratedNode, type HydratedPlanet, PLANET_AND_NODE_NAMES, Planet, SIGNS, type SynastryChart, type SynastryChartOptions, VirtualNodes, type ZodiacPosition, closeSwissEph, computeAspects, computeMidpoints, computeSynastryAspects, findHouseOf, formatDegreeMinutes, getAspectMatch, getBirthChart, getCompositeChart, getSwissEph, getSynastryChart, getZodiacPosition, normalizeAngle };
450
+ export { type AnnualProfection, type AspectEdge, type AspectName, type AspectPerfection, type AspectSpec, type BirthChart, type BirthChartOptions, CalcFlag, type CompositeChart, type CompositeChartOptions, DEFAULT_ASPECT_SPECS, DOMICILE_RULERS, type DecanResult, type DodecatemoriaResult, EXALTATIONS, type EssentialDignityResult, type FirdariaMajorPeriod, type FirdariaOptions, type FirdariaPlanet, type FirdariaResult, type FirdariaSubPeriod, HouseSystem, type HydratedNode, type HydratedPlanet, type MonthlyProfection, type MonthlyProfectionsResult, PLANET_AND_NODE_NAMES, Planet, SIGNS, SLOW_PLANETS, type Sign, type SolarReturnChart, type SolarReturnOptions, type SynastryChart, type SynastryChartOptions, type TraditionalPlanet, type TransitAspectEdge, type TransitAspectPoint, type TransitChart, type TransitChartOptions, type TransitPlanet, type TransitRangeOptions, type TransitRangeResult, type TwoChartOptions, VirtualNodes, type ZodiacPosition, closeSwissEph, computeAspects, computeMidpoints, computeSynastryAspects, computeTransitAspects, findHouseOf, formatDegreeMinutes, getAnnualProfection, getAspectMatch, getBirthChart, getCompositeChart, getDecan, getDetriment, getDodecatemoria, getDomicileRuler, getEssentialDignity, getExaltation, getFall, getFirdaria, getMonthlyProfections, getOppositeSign, getSolarReturnChart, getSwissEph, getSynastryChart, getTransitChart, getTransitRange, getZodiacPosition, normalizeAngle, shorterArcMidpoint };
@@ -148,11 +148,142 @@ declare function computeSynastryAspects(planetsA: Record<string, {
148
148
  }>, planetsB: Record<string, {
149
149
  longitude: number;
150
150
  }>, specs?: AspectSpec[]): AspectEdge[];
151
+ /** Shorter-arc midpoint of two ecliptic longitudes. */
152
+ declare function shorterArcMidpoint(a: number, b: number): number;
151
153
  declare function computeMidpoints(planetsA: Record<string, {
152
154
  longitude: number;
153
155
  }>, planetsB: Record<string, {
154
156
  longitude: number;
155
157
  }>): Record<string, number>;
158
+ interface TransitAspectEdge extends AspectEdge {
159
+ applying: boolean;
160
+ retrograde: boolean;
161
+ category: "slow" | "fast";
162
+ }
163
+ interface TransitAspectPoint {
164
+ longitude: number;
165
+ longitudeSpeed?: number;
166
+ }
167
+ declare const SLOW_PLANETS: Set<string>;
168
+ /**
169
+ * Compute transit-to-natal aspects with applying/separating, retrograde, and speed category.
170
+ *
171
+ * planetA = transit planet, planetB = natal planet/point.
172
+ */
173
+ declare function computeTransitAspects(transitPlanets: Record<string, TransitAspectPoint>, natalPlanets: Record<string, TransitAspectPoint>, specs?: AspectSpec[]): TransitAspectEdge[];
174
+
175
+ /**
176
+ * Essential Dignity Table — Traditional Hellenistic rulership data.
177
+ * Pure math, no WASM dependency.
178
+ */
179
+
180
+ type Sign = (typeof SIGNS)[number];
181
+ type TraditionalPlanet = "Sun" | "Moon" | "Mercury" | "Venus" | "Mars" | "Jupiter" | "Saturn";
182
+ interface EssentialDignityResult {
183
+ domicile: boolean;
184
+ exaltation: boolean;
185
+ detriment: boolean;
186
+ fall: boolean;
187
+ domicileRuler: TraditionalPlanet;
188
+ peregrine: boolean;
189
+ }
190
+ declare const DOMICILE_RULERS: Record<Sign, TraditionalPlanet>;
191
+ declare const EXALTATIONS: Record<TraditionalPlanet, {
192
+ sign: Sign;
193
+ degree: number;
194
+ }>;
195
+ declare function getDomicileRuler(sign: Sign): TraditionalPlanet;
196
+ declare function getExaltation(planet: TraditionalPlanet): {
197
+ sign: Sign;
198
+ degree: number;
199
+ };
200
+ declare function getOppositeSign(sign: Sign): Sign;
201
+ /** Signs where the planet is in detriment (opposite of its domicile signs). */
202
+ declare function getDetriment(planet: TraditionalPlanet): Sign[];
203
+ /** Sign where the planet is in fall (opposite of its exaltation sign). */
204
+ declare function getFall(planet: TraditionalPlanet): Sign;
205
+ declare function getEssentialDignity(planet: TraditionalPlanet, sign: Sign): EssentialDignityResult;
206
+
207
+ /**
208
+ * Decan (face) lookup — Chaldean rulers + Golden Dawn tarot correspondence.
209
+ * Pure math, no WASM dependency.
210
+ */
211
+
212
+ interface DecanResult {
213
+ sign: string;
214
+ decanNumber: 1 | 2 | 3;
215
+ ruler: TraditionalPlanet;
216
+ tarotCard: string;
217
+ startDegree: number;
218
+ endDegree: number;
219
+ degreeWithinSign: number;
220
+ }
221
+ declare function getDecan(longitude: number): DecanResult;
222
+
223
+ /**
224
+ * Dodecatemoria (12th parts) — traditional Hellenistic technique.
225
+ * Pure math, no WASM dependency.
226
+ */
227
+ interface DodecatemoriaResult {
228
+ originalSign: string;
229
+ originalDegree: number;
230
+ dodecatemoriaSign: string;
231
+ dodecatemoriaIndex: number;
232
+ }
233
+ declare function getDodecatemoria(longitude: number): DodecatemoriaResult;
234
+
235
+ /**
236
+ * Annual & Monthly Profections — traditional Hellenistic time-lord technique.
237
+ * Pure math. Requires a whole-sign BirthChart for house sign lookup.
238
+ */
239
+
240
+ interface AnnualProfection {
241
+ age: number;
242
+ house: number;
243
+ sign: string;
244
+ ruler: TraditionalPlanet;
245
+ targetYear: number;
246
+ }
247
+ interface MonthlyProfection {
248
+ month: number;
249
+ startDate: Date;
250
+ sign: string;
251
+ ruler: TraditionalPlanet;
252
+ }
253
+ interface MonthlyProfectionsResult {
254
+ annualProfection: AnnualProfection;
255
+ months: MonthlyProfection[];
256
+ }
257
+ declare function getAnnualProfection(natalChart: BirthChart, birthDate: Date, targetYear?: number): AnnualProfection;
258
+ declare function getMonthlyProfections(natalChart: BirthChart, birthDate: Date, targetYear?: number): MonthlyProfectionsResult;
259
+
260
+ /**
261
+ * Firdaria — traditional planetary period system.
262
+ * Pure math, no WASM dependency.
263
+ */
264
+ type FirdariaPlanet = "Sun" | "Moon" | "Mercury" | "Venus" | "Mars" | "Jupiter" | "Saturn" | "NorthNode" | "SouthNode";
265
+ interface FirdariaSubPeriod {
266
+ planet: FirdariaPlanet;
267
+ startDate: Date;
268
+ endDate: Date;
269
+ }
270
+ interface FirdariaMajorPeriod {
271
+ planet: FirdariaPlanet;
272
+ years: number;
273
+ startDate: Date;
274
+ endDate: Date;
275
+ subPeriods: FirdariaSubPeriod[];
276
+ }
277
+ interface FirdariaResult {
278
+ sect: "diurnal" | "nocturnal";
279
+ currentMajor: FirdariaMajorPeriod;
280
+ currentSub: FirdariaSubPeriod;
281
+ allPeriods: FirdariaMajorPeriod[];
282
+ }
283
+ interface FirdariaOptions {
284
+ nodeSubPeriodStart?: "jupiter-saturn" | "sun-mars";
285
+ }
286
+ declare function getFirdaria(birthDate: Date, isDiurnal: boolean, targetDate?: Date, options?: FirdariaOptions): FirdariaResult;
156
287
 
157
288
  /**
158
289
  * Astrological calculations using Swiss Ephemeris
@@ -202,6 +333,7 @@ interface BirthChart {
202
333
  };
203
334
  };
204
335
  aspects: AspectEdge[];
336
+ sect: "diurnal" | "nocturnal";
205
337
  }
206
338
  /**
207
339
  * Calculate a birth chart using Swiss Ephemeris
@@ -226,22 +358,18 @@ declare function formatDegreeMinutes(decimalDegrees: number): string;
226
358
  */
227
359
  declare function getZodiacPosition(longitude: number, houseCusps: number[]): ZodiacPosition;
228
360
  declare function findHouseOf(longitude: number, housePositions: number[]): number;
229
- interface SynastryChartOptions {
361
+ interface TwoChartOptions {
230
362
  chartA: BirthChartOptions;
231
363
  chartB: BirthChartOptions;
232
364
  aspectSpecs?: AspectSpec[];
233
365
  }
366
+ type SynastryChartOptions = TwoChartOptions;
367
+ type CompositeChartOptions = TwoChartOptions;
234
368
  interface SynastryChart {
235
369
  chartA: BirthChart;
236
370
  chartB: BirthChart;
237
371
  aspects: AspectEdge[];
238
372
  }
239
- declare function getSynastryChart(options: SynastryChartOptions): Promise<SynastryChart>;
240
- interface CompositeChartOptions {
241
- chartA: BirthChartOptions;
242
- chartB: BirthChartOptions;
243
- aspectSpecs?: AspectSpec[];
244
- }
245
373
  interface CompositeChart {
246
374
  chartA: BirthChart;
247
375
  chartB: BirthChart;
@@ -253,6 +381,70 @@ interface CompositeChart {
253
381
  compositeHouses: ZodiacPosition[];
254
382
  aspects: AspectEdge[];
255
383
  }
384
+ declare function getSynastryChart(options: SynastryChartOptions): Promise<SynastryChart>;
256
385
  declare function getCompositeChart(options: CompositeChartOptions): Promise<CompositeChart>;
386
+ interface TransitChartOptions {
387
+ natal: BirthChartOptions;
388
+ transitDate: Date;
389
+ transitLatitude?: number;
390
+ transitLongitude?: number;
391
+ transitTimeZoneSettings?: TimeZoneOptions;
392
+ aspectSpecs?: AspectSpec[];
393
+ maxOrb?: number;
394
+ transitPlanets?: string[];
395
+ natalPlanets?: string[];
396
+ aspectFilter?: AspectName[];
397
+ }
398
+ interface TransitPlanet extends HydratedPlanet {
399
+ retrograde: boolean;
400
+ natalHouse: number;
401
+ }
402
+ interface TransitChart {
403
+ natalChart: BirthChart;
404
+ transitDateUtc: Date;
405
+ transitPlanets: Record<string, TransitPlanet>;
406
+ aspects: TransitAspectEdge[];
407
+ }
408
+ interface TransitRangeOptions extends Omit<TransitChartOptions, "transitDate"> {
409
+ from: Date;
410
+ to: Date;
411
+ stepDays?: number;
412
+ }
413
+ interface AspectPerfection {
414
+ transitPlanet: string;
415
+ natalPlanet: string;
416
+ aspect: AspectName;
417
+ exactDate: Date;
418
+ exactOrb: number;
419
+ retrograde: boolean;
420
+ category: "slow" | "fast";
421
+ }
422
+ interface TransitRangeResult {
423
+ natalChart: BirthChart;
424
+ from: Date;
425
+ to: Date;
426
+ perfections: AspectPerfection[];
427
+ }
428
+ declare function getTransitChart(options: TransitChartOptions): Promise<TransitChart>;
429
+ declare function getTransitRange(options: TransitRangeOptions): Promise<TransitRangeResult>;
430
+ interface SolarReturnOptions {
431
+ natal: BirthChartOptions;
432
+ year: number;
433
+ solarReturnLatitude?: number;
434
+ solarReturnLongitude?: number;
435
+ solarReturnHouseSystem?: HouseSystem;
436
+ }
437
+ interface SolarReturnChart {
438
+ natalChart: BirthChart;
439
+ solarReturnChart: BirthChart;
440
+ exactReturnDate: Date;
441
+ natalSunLongitude: number;
442
+ year: number;
443
+ }
444
+ /**
445
+ * Calculate a Solar Return chart — the moment the transiting Sun returns
446
+ * to its natal longitude in the given year.
447
+ */
448
+ declare function getSolarReturnChart(options: SolarReturnOptions): Promise<SolarReturnChart>;
257
449
 
258
- export { type AspectEdge, type AspectName, type AspectSpec, type BirthChart, type BirthChartOptions, CalcFlag, type CompositeChart, type CompositeChartOptions, DEFAULT_ASPECT_SPECS, HouseSystem, type HydratedNode, type HydratedPlanet, PLANET_AND_NODE_NAMES, Planet, SIGNS, type SynastryChart, type SynastryChartOptions, VirtualNodes, type ZodiacPosition, closeSwissEph, computeAspects, computeMidpoints, computeSynastryAspects, findHouseOf, formatDegreeMinutes, getAspectMatch, getBirthChart, getCompositeChart, getSwissEph, getSynastryChart, getZodiacPosition, normalizeAngle };
450
+ export { type AnnualProfection, type AspectEdge, type AspectName, type AspectPerfection, type AspectSpec, type BirthChart, type BirthChartOptions, CalcFlag, type CompositeChart, type CompositeChartOptions, DEFAULT_ASPECT_SPECS, DOMICILE_RULERS, type DecanResult, type DodecatemoriaResult, EXALTATIONS, type EssentialDignityResult, type FirdariaMajorPeriod, type FirdariaOptions, type FirdariaPlanet, type FirdariaResult, type FirdariaSubPeriod, HouseSystem, type HydratedNode, type HydratedPlanet, type MonthlyProfection, type MonthlyProfectionsResult, PLANET_AND_NODE_NAMES, Planet, SIGNS, SLOW_PLANETS, type Sign, type SolarReturnChart, type SolarReturnOptions, type SynastryChart, type SynastryChartOptions, type TraditionalPlanet, type TransitAspectEdge, type TransitAspectPoint, type TransitChart, type TransitChartOptions, type TransitPlanet, type TransitRangeOptions, type TransitRangeResult, type TwoChartOptions, VirtualNodes, type ZodiacPosition, closeSwissEph, computeAspects, computeMidpoints, computeSynastryAspects, computeTransitAspects, findHouseOf, formatDegreeMinutes, getAnnualProfection, getAspectMatch, getBirthChart, getCompositeChart, getDecan, getDetriment, getDodecatemoria, getDomicileRuler, getEssentialDignity, getExaltation, getFall, getFirdaria, getMonthlyProfections, getOppositeSign, getSolarReturnChart, getSwissEph, getSynastryChart, getTransitChart, getTransitRange, getZodiacPosition, normalizeAngle, shorterArcMidpoint };