Internal module guide. This module is now part of @astrology/astronomy-contracts; use the public package README for application setup.

adapter-contract module

@astrology/astronomy-contracts is the standalone TypeScript ESM contract for ephemeris adapters. It has no runtime dependencies, native imports, server, environment configuration, or HTTP status mapping. It owns canonical identifiers, request/result types, EphemerisAdapter, runtime validation, immutable fluent requests, and typed errors.

Consumer workspace packages declare "@astrology/astronomy-contracts": "workspace:*" in their dependencies. Build the contract before its consumers with pnpm build:ephemeris, or build this package alone with pnpm build:astronomy-contracts.

import { PositionQuery, type EphemerisAdapter } from '@astrology/astronomy-contracts';

export async function loadPositions(provider: EphemerisAdapter) {
  const request = PositionQuery.at('2000-01-01T12:00:00Z', { zodiac: 'tropical' })
    .forBodies('sun', 'moon')
    .withSpeed()
    .build();

  return provider.positions(request);
}

The port exposes capabilities(), positions(request), and houses(request), all returning Promises. Results contain { data, declaration }. Longitudes/latitudes use degrees, distances AU (astronomical units), angular speeds degrees/day, and radial speeds AU/day. Absent speeds are null. Instants are offset-bearing ISO strings with at most milliseconds or integer epoch milliseconds. Callers resolve civil timezones.

Capabilities declare supported features, zodiacs, bodies, house systems, ayanamsas, coverage and precision. UNSUPPORTED_FEATURE is the typed refusal for an unsupported operation or zodiac. A future NASA adapter can advertise only tropical positions with empty house and ayanamsa lists, and null native binding/tidal/flag metadata. Shared validation checks canonical shape; each adapter checks its own capability eligibility. No NASA runtime implementation ships here.

AdapterError.code comes from ERROR_CODES. There is no status property: consumers choose how to present or transport failures. Canonical arrays describe the full vocabulary, not a promise that every provider supports every value. PositionQuery is an immutable convenience; plain DTOs use the same validateRequest boundary.

pnpm --filter @astrology/astronomy-contracts test builds and runs the package’s tests. Contract tests require no ephemeris files, Swiss binding, network, or worker process. pnpm check:ephemeris also checks a compile-only consumer representing NASA’s narrower capabilities; this verifies type compatibility, not a live NASA integration.

See the module architecture and Swiss implementation.