ether-to-astro 1.2.0 → 1.3.0

package/dist/astro-service.d.ts

@@ -1,12 +1,12 @@
+import type { GenerateChartInput, GenerateTransitChartInput, GetElectionalContextInput, GetHousesInput, GetRisingSignWindowsInput, GetTransitsInput, ServiceResult, SetNatalChartInput } from './astro-service/service-types.js';
 import { ChartRenderer } from './charts.js';
 import { EclipseCalculator } from './eclipses.js';
 import type { McpStartupDefaults } from './entrypoint.js';
 import { EphemerisCalculator } from './ephemeris.js';
 import { HouseCalculator } from './houses.js';
 import { RiseSetCalculator } from './riseset.js';
-import { type Disambiguation } from './time-utils.js';
 import { TransitCalculator } from './transits.js';
-import { type AspectType, type ElectionalHouseSystem, type HouseSystem, type NatalChart, type PlanetPosition } from './types.js';
+import type { NatalChart } from './types.js';
 interface AstroServiceDependencies {
     ephem?: EphemerisCalculator;
     transitCalc?: TransitCalculator;
@@ -18,72 +18,6 @@ interface AstroServiceDependencies {
     now?: () => Date;
     writeFile?: (path: string, data: string | Buffer, encoding?: BufferEncoding) => Promise<void>;
 }
-export interface SetNatalChartInput {
-    name: string;
-    year: number;
-    month: number;
-    day: number;
-    hour: number;
-    minute: number;
-    latitude: number;
-    longitude: number;
-    timezone: string;
-    house_system?: HouseSystem;
-    birth_time_disambiguation?: Disambiguation;
-}
-export interface GetTransitsInput {
-    date?: string;
-    categories?: string[];
-    include_mundane?: boolean;
-    days_ahead?: number;
-    mode?: 'snapshot' | 'best_hit' | 'forecast';
-    max_orb?: number;
-    exact_only?: boolean;
-    applying_only?: boolean;
-}
-export interface GetElectionalContextInput {
-    date: string;
-    time: string;
-    timezone: string;
-    latitude: number;
-    longitude: number;
-    house_system?: ElectionalHouseSystem;
-    include_ruler_basics?: boolean;
-    include_planetary_applications?: boolean;
-    orb_degrees?: number;
-}
-export interface GetHousesInput {
-    system?: string;
-}
-export interface GetRisingSignWindowsInput {
-    date: string;
-    latitude: number;
-    longitude: number;
-    timezone: string;
-    mode?: 'approximate' | 'exact';
-}
-export interface GenerateChartInput {
-    theme?: 'light' | 'dark';
-    format?: 'svg' | 'png' | 'webp';
-    output_path?: string;
-}
-export interface GenerateTransitChartInput extends GenerateChartInput {
-    date?: string;
-}
-export interface ServiceResult<T> {
-    data: T;
-    text: string;
-}
-export interface MundaneAspect {
-    id: string;
-    planetA: PlanetPosition['planet'];
-    planetB: PlanetPosition['planet'];
-    aspect: AspectType;
-    orb: number;
-    isApplying: boolean;
-    longitudeA: number;
-    longitudeB: number;
-}
 interface ChartServiceResult {
     format: 'svg' | 'png' | 'webp';
     outputPath?: string;
@@ -94,13 +28,15 @@ interface ChartServiceResult {
         mimeType: string;
     };
 }
-export declare function parseDateOnlyInput(dateStr: string): {
-    year: number;
-    month: number;
-    day: number;
-    hour: number;
-    minute: number;
-};
+export { parseDateOnlyInput } from './astro-service/date-input.js';
+export type { GenerateChartInput, GenerateTransitChartInput, GetElectionalContextInput, GetHousesInput, GetRisingSignWindowsInput, GetTransitsInput, ServiceResult, SetNatalChartInput, } from './astro-service/service-types.js';
+/**
+ * Shared service facade used by both the MCP server and the CLI.
+ *
+ * @remarks
+ * Public methods remain the stable orchestration boundary while domain-specific
+ * internals can be extracted behind the class without changing callers.
+ */
 export declare class AstroService {
     readonly ephem: EphemerisCalculator;
     readonly transitCalc: TransitCalculator;
@@ -109,39 +45,115 @@ export declare class AstroService {
     readonly eclipseCalc: EclipseCalculator;
     readonly chartRenderer: ChartRenderer;
     readonly mcpStartupDefaults: Readonly<McpStartupDefaults>;
+    private readonly transitService;
+    private readonly electionalService;
+    private readonly risingSignService;
+    private readonly natalService;
+    private readonly skyService;
+    private readonly chartOutputService;
     private readonly now;
     private readonly writeFileFn;
     constructor(deps?: AstroServiceDependencies);
+    /**
+     * Format user-facing timestamps using the current startup default weekday policy.
+     */
     private formatTimestamp;
-    private normalizeLongitude;
-    private getSignAndDegree;
-    private getHouseNumber;
-    private resolveHouseSystem;
-    private resolveTimezones;
+    /**
+     * Resolve the timezone used for user-facing timestamps and labels.
+     *
+     * @remarks
+     * Explicit per-call timezone wins, then startup defaults, then the natal chart
+     * timezone, and finally UTC.
+     */
     resolveReportingTimezone(explicitTimezone?: string, natalTimezone?: string): string;
+    /**
+     * Initialize the underlying ephemeris engine.
+     */
     init(): Promise<void>;
+    /**
+     * Report whether the ephemeris engine has been initialized.
+     */
     isInitialized(): boolean;
+    /**
+     * Build and cache the shared natal chart payload used by later workflows.
+     *
+     * @remarks
+     * This preserves the existing natal contract, including polar-latitude house
+     * fallback behavior and the current user-facing summary text.
+     */
     setNatalChart(input: SetNatalChartInput): ServiceResult<Record<string, unknown>> & {
         chart: NatalChart;
     };
+    /**
+     * Calculate natal transits while preserving the public service contract.
+     *
+     * @remarks
+     * Transit day interpretation uses the natal chart timezone for calculation and
+     * may use a different reporting timezone for labels when startup defaults are set.
+     */
     getTransits(natalChart: NatalChart, input?: GetTransitsInput): ServiceResult<Record<string, unknown>>;
-    private getMundaneWeather;
-    private getMundaneAspects;
-    private getMundaneDay;
+    /**
+     * Produce deterministic electional context for a single local instant.
+     *
+     * @remarks
+     * Electional local times keep strict DST rejection semantics for ambiguous or
+     * nonexistent wall-clock instants.
+     */
     getElectionalContext(input: GetElectionalContextInput): ServiceResult<Record<string, unknown>>;
+    /**
+     * Calculate house cusps and angles for a natal chart.
+     *
+     * @remarks
+     * House-system resolution still respects explicit per-call input, then stored
+     * chart preference, then startup defaults.
+     */
     getHouses(natalChart: NatalChart, input?: GetHousesInput): ServiceResult<Record<string, unknown>>;
+    /**
+     * Find rising-sign windows across a calendar day at a specific location.
+     *
+     * @remarks
+     * `exact` mode refines sign boundaries more aggressively; `approximate` mode
+     * keeps the cheaper bucketed scan behavior.
+     */
     getRisingSignWindows(input: GetRisingSignWindowsInput): ServiceResult<Record<string, unknown>>;
-    private getElectionalApplyingAspects;
-    private isElectionalAspectApplying;
-    private getSignedAngularDifference;
-    private getElectionalPhaseName;
-    private getTraditionalSignRuler;
+    /**
+     * Return the currently retrograde planets for the requested reporting timezone.
+     */
     getRetrogradePlanets(timezone?: string): ServiceResult<Record<string, unknown>>;
+    /**
+     * Return the next rise and set events after the local day anchor for the chart location.
+     *
+     * @remarks
+     * The lookup anchor remains local midnight in the natal chart timezone even
+     * when reporting text uses a preferred reporting timezone.
+     */
     getRiseSetTimes(natalChart: NatalChart): Promise<ServiceResult<Record<string, unknown>>>;
+    /**
+     * Return current asteroid and node positions for the requested reporting timezone.
+     */
     getAsteroidPositions(timezone?: string): ServiceResult<Record<string, unknown>>;
+    /**
+     * Look up the next solar and lunar eclipses after the current instant.
+     */
     getNextEclipses(timezone?: string): ServiceResult<Record<string, unknown>>;
+    /**
+     * Summarize process-local server state and configured startup defaults.
+     */
     getServerStatus(natalChart: NatalChart | null): ServiceResult<Record<string, unknown>>;
+    /**
+     * Generate a natal chart image or SVG for the current chart.
+     *
+     * @remarks
+     * When `output_path` is omitted the payload is returned inline; otherwise the
+     * rendered asset is written to disk and only path metadata is returned.
+     */
     generateNatalChart(natalChart: NatalChart, input?: GenerateChartInput): Promise<ChartServiceResult>;
+    /**
+     * Generate a transit chart image or SVG for a target date.
+     *
+     * @remarks
+     * Omitted dates still resolve to local noon in the natal chart timezone before
+     * rendering so date-only behavior stays stable across timezone conversions.
+     */
     generateTransitChart(natalChart: NatalChart, input?: GenerateTransitChartInput): Promise<ChartServiceResult>;
 }
-export {};