celestrak 1.0.4

A pure-Dart client for fetching, parsing, and caching satellite TLE and OMM orbital data from CelesTrak and Space-Track. No Flutter dependency.

Changelog

All notable changes to this project are documented here. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.0.4 - 2026-06-10

Fixed

• Completed WASM compatibility. Removed all unconditional dart:io imports from the public API chain:
  • celestrak_client.dart — replaced import 'dart:io' show Directory and FileCacheStore(Directory(cacheDir)) with a conditional-import factory (default_cache_store_io.dart / default_cache_store_stub.dart). On web/WASM, cacheDir is ignored and a MemoryCacheStore is used; on native, behaviour is unchanged.
  • spacetrack_data_source.dart — replaced import 'dart:io' show SocketException with the same conditional-import shim introduced in v1.0.3 (socket_exception_io.dart / socket_exception_stub.dart).
  • The package now passes pub.dev WASM compatibility checks across the full public API surface.

1.0.3 - 2026-06-09

Fixed

• Fixed WASM incompatibility in http_transport.dart. The unconditional import 'dart:io' (used only for SocketException) is replaced with a conditional import: dart:io is loaded on native platforms, a no-op stub on web/WASM. SocketException handling is preserved on native; the package now passes WASM compatibility checks on pub.dev.

1.0.2 - 2026-06-09

Fixed

• Removed dart:io import from failures.dart — it was only referenced in a doc comment. The package now passes WASM compatibility checks on pub.dev.

1.0.1 - 2026-06-09

Added

• example/main.dart — runnable CLI script demonstrating every public API: fetchByNoradId, fetchCategory, fetchCategoryByGroup, fetchByName, fetchByIntlDesignator, cacheAge, clearCache, isStale, and all cache control parameters (allowStale, forceCache, ttl).

1.0.0 - 2026-06-05

Changed

• Declared stable public API; no breaking changes from 0.0.1.

0.1.0 UNRELEASED

Added

Domain models

• SatelliteTle — immutable orbital record carrying noradId, name, verbatim line1/line2 strings, epoch, fetchedAt, source, and an optional Omm payload. Provides age, ageAt(DateTime), isStale, classification, copyWith, and value equality.
• Omm — full CCSDS Orbit Mean-Elements Message mapping all mandatory OMM keywords plus CelesTrak header fields. null objectName/objectId are tolerated for analyst (80000-series) objects.
• TleSource enum — celestrak, spacetrack, local; stamps every SatelliteTle with its data provenance.
• CelestrakFormat enum — omm (recommended default, supports 9-digit catalog numbers) and tle (legacy 3-line format).
• SatelliteCategory enum — named CelesTrak groups: stations, starlink, weather, amateur, visual, gps, galileo, glonass, cosmos2251Debris, active, lastThirtyDays. Each value exposes a .group string for the GROUP= query parameter.

Parsers

• OmmParser — stateless, reusable parser for CelesTrak OMM JSON. Supports single-record parse() and lazy parseAllLazy() for large category responses. All failures surface as OmmParseException.
• TLE parser (internal) — splits 3-line records, validates mod-10 checksum (toggle-able), decodes 2-digit-year + fractional-DOY epoch, and handles 1–9-digit NORAD catalog IDs.
• Dual-format stitch — when fetching in OMM format the pipeline issues a companion FORMAT=TLE request to obtain verbatim TLE lines required by SGP4 propagators. Objects with catalog numbers ≥ 100 000 (alpha-5 encoding) gracefully receive empty line1/line2 when absent from the TLE response.

Cache pipeline

• CacheStore — abstract interface for key-value byte caching with read, write, age, and clear operations.
• MemoryCacheStore — in-memory CacheStore implementation for testing and web targets (where file I/O is unavailable).
• FileCacheStore (internal) — dart:io-backed store with write-temp-then- rename atomicity and sidecar timestamp files for age tracking. Corrupt or truncated files are treated as cache misses.
• CacheKeyBuilder (internal) — builds filename-safe, path-traversal-free cache keys encoding {queryType, queryValue, format, source}.
• Clock / SystemClock — injectable time source used throughout the pipeline for TTL checks, age calculations, and staleness classification.
• StalenessChecker — classifies orbital data against a configurable staleThreshold (default 3 days). isFresh(cacheAge, ttl:) determines cache validity; isStale(epoch) determines orbital data accuracy.
• defaultStaleThreshold constant — Duration(days: 3); LEO-conservative default; override for highly elliptical orbits or debris with fast decay.

Cache policies: allowStale and forceCache

• allowStale parameter (all fetch methods) — when true and the network request fails, the repository returns a stale cached entry (if present) rather than re-throwing. The returned record carries TleSource.local and its isStale flag reflects the orbital epoch age. When false (default), any network failure with no fresh cache raises NetworkException.
• forceCache parameter (all fetch methods) — when true, the network is never contacted. If no cached entry exists a CacheMissException is thrown immediately. When both forceCache: true and allowStale: true are supplied, forceCache takes unconditional priority.
• Stale-while-revalidate — TTL-expired entries trigger a remote fetch; if the fetch succeeds the cache is refreshed. If the fetch fails and allowStale: true, the expired entry is returned with TleSource.local.

isStale on SatelliteTle

• SatelliteTle.isStale({DateTime? now, Duration staleThreshold}) — checks whether the orbital epoch has aged past staleThreshold (default 3 days). Accepts an optional pinned now for deterministic tests.
• CelestrakClient.isStale(SatelliteTle) — convenience method on the facade that uses the client's configured staleThreshold.

Repository and client facades

• TleRepository — abstract interface describing the cache → TTL → fetch → parse → stamp pipeline. Supports fetchByNoradId, fetchCategory, fetchCategoryByGroup, fetchByName, fetchByIntlDesignator, per-method cache-age queries (cacheAge, categoryAge, groupAge, nameAge, intlDesignatorAge), and clearCache.
• CelestrakClient — high-level facade over TleRepository.
  • Default constructor: supply a cacheDir path; the client owns an internal http.Client and a FileCacheStore. Call dispose when done.
  • CelestrakClient.withStore: inject a custom CacheStore and http.Client; lifecycle remains the caller's responsibility.
  • Configuration parameters: defaultTtl, defaultFormat, timeout, maxAttempts, staleThreshold, clock, useIsolate.
  • fetchByNoradId(int noradId, ...) — single-object lookup via CATNR=<id>.
  • fetchCategory(SatelliteCategory, ...) — group lookup via GROUP=<category.group>.
  • fetchCategoryByGroup(String group, ...) — arbitrary group string passthrough.
  • fetchByName(String name, ...) — name substring search via NAME=<name>; returns an empty list on no match (never throws).
  • fetchByIntlDesignator(String, ...) — international designator lookup via INTDES=<designator>; returns an empty list on no match.
  • cacheAge, categoryAge, groupAge, nameAge, intlDesignatorAge — per-key cache-age inspection.
  • clearCache({String? keyPrefix}) — removes all cache entries or those matching a prefix.
  • isStale(SatelliteTle) — staleness convenience using the client's configured threshold.
  • dispose() — closes the owned http.Client (no-op for withStore).
• HttpTransport (internal) — bounded retry with exponential backoff (5xx / TimeoutException / SocketException only; 4xx never retried), HTTPS enforcement, and injectable http.Client.

Space-Track support

• SpaceTrackClient — credentialed facade for Space-Track.org GP API.
  • Performs POST-based login and holds the session cookie in memory only; credentials are never written to disk.
  • SpaceTrackClient.withClient constructor for test injection.
  • Credential gating: pass null or empty credentials to construct a disabled client; isEnabled returns false and fetchByQuery throws StateError rather than an authentication error.
  • fetchByQuery(SpaceTrackQuery) — fetches and parses a single GP record; stamps result with TleSource.spacetrack.
  • Enforces a configurable minimum inter-request interval (minRequestInterval, default 2 s) as a courtesy to Space-Track rate limits.
  • Idempotent dispose().
• SpaceTrackQuery — immutable value object for Space-Track queries. Currently supports SpaceTrackQuery.byNoradId(int).
• AuthenticationException — raised on HTTP 401/403 from Space-Track.
• RateLimitException — raised on HTTP 429; carries optional retryAfter.

Error hierarchy

• CelestrakException (sealed base) — all library exceptions share a common message field and are exhaustively matchable in a switch.
• NetworkException — transport failure; carries optional statusCode, uri, and cause.
• SatelliteNotFoundException — CelesTrak returned the "No GP data found" sentinel. noradId is 0 for group/category queries.
• OmmParseException — OMM JSON parse failure; optional field names the offending keyword.
• TleParseException — TLE text parse failure; optional field names the offending line.
• CacheMissException — forceCache: true with no cached entry; key identifies the absent cache key.
• AuthenticationException — Space-Track 401/403; carries statusCode.
• RateLimitException — Space-Track 429; carries optional retryAfter.

Benchmark extension point

• ParseBenchmarkHook / NullParseBenchmarkHook — interface for measuring parse duration in multi-record category responses. Inject into OmmParser to collect timing signals without modifying the production code path.

Configuration constants

• kDefaultTtl — Duration(hours: 2).
• kDefaultMaxAttempts — 5 (1 initial + 4 retries).
• kDefaultTimeout — Duration(seconds: 30).

Public API surface

• Frozen public API surface: every symbol exported from package:celestrak is intentional and documented. Internal types (HttpTransport, CacheKeyBuilder, TleOmmStitcher, FileCacheStore, backoff constants) are not part of the public contract.

0.0.1 - 2026-05-30

Added

• Initial package scaffold.