@mostlyrightmd/core 0.1.0-rc.7

package/dist/index.d.cts

@@ -0,0 +1,559 @@
+interface ObservationV1 {
+    /**
+     * units: celsius — bounded
+     */
+    dew_point_c?: null | number;
+    /**
+     * observation valid time
+     */
+    event_time: string;
+    /**
+     * raw METAR text if source has it; null for AWC JSON (structured-only)
+     */
+    metar_raw?: null | string;
+    /**
+     * METAR | SPECI; defaults METAR when source can't distinguish (e.g. AWC JSON)
+     */
+    observation_type: "METAR" | "SPECI";
+    /**
+     * units: mm — hourly precip (METAR p01i, converted from inches)
+     */
+    precip_mm_1h?: null | number;
+    /**
+     * units: meters — first cloud layer base height (converted from feet)
+     */
+    sky_base_1_m?: null | number;
+    /**
+     * units: meters
+     */
+    sky_base_2_m?: null | number;
+    /**
+     * units: meters
+     */
+    sky_base_3_m?: null | number;
+    /**
+     * units: meters
+     */
+    sky_base_4_m?: null | number;
+    /**
+     * first cloud layer cover code
+     */
+    sky_cover_1?: "BKN" | "CLR" | "FEW" | "OVC" | "SCT" | "VV" | null;
+    /**
+     * second layer; null if not present
+     */
+    sky_cover_2?: "BKN" | "CLR" | "FEW" | "OVC" | "SCT" | "VV" | null;
+    /**
+     * third layer; null if not present
+     */
+    sky_cover_3?: "BKN" | "CLR" | "FEW" | "OVC" | "SCT" | "VV" | null;
+    /**
+     * fourth layer; null if not present
+     */
+    sky_cover_4?: "BKN" | "CLR" | "FEW" | "OVC" | "SCT" | "VV" | null;
+    /**
+     * units: hPa — sea-level pressure (canonical aviation unit, not converted across modes)
+     */
+    slp_hpa?: null | number;
+    /**
+     * ICAO/ASOS station ID (e.g. KORD)
+     */
+    station: string;
+    /**
+     * units: celsius — bounded TEMP_MIN_C..TEMP_MAX_C
+     */
+    temp_c?: null | number;
+    /**
+     * units: meters — converted from statute miles
+     */
+    visibility_m?: null | number;
+    /**
+     * units: degrees — 0-360, bounded
+     */
+    wind_dir_deg?: number | null;
+    /**
+     * units: m/s — converted from kt
+     */
+    wind_gust_ms?: null | number;
+    /**
+     * units: m/s — converted from kt
+     */
+    wind_speed_ms?: null | number;
+}
+
+interface ForecastIemMosV1 {
+    /**
+     * units: celsius
+     */
+    dew_point_c?: null | number;
+    /**
+     * units: hours — (valid_at - issued_at).total_seconds() / 3600
+     */
+    forecast_hour: number;
+    /**
+     * model run time (from source `runtime` field)
+     */
+    issued_at: string;
+    /**
+     * e.g. NBE, GFS, LAV, MET
+     */
+    model: string;
+    /**
+     * units: probability — bounded [0, 1]
+     */
+    precip_probability?: null | number;
+    /**
+     * units: percent — bounded [0, 100]
+     */
+    sky_cover_pct?: number | null;
+    station: string;
+    /**
+     * units: celsius
+     */
+    temp_c?: null | number;
+    /**
+     * forecast target time (from source `ftime`)
+     */
+    valid_at: string;
+    /**
+     * units: degrees
+     */
+    wind_dir_deg?: number | null;
+    /**
+     * units: m/s
+     */
+    wind_speed_ms?: null | number;
+}
+
+interface SettlementCliV1 {
+    /**
+     * NWS CLI data-quality marker (Pitfall 6/16). Allows downstream code to filter or weight settlement rows by issuer quality without re-parsing the product header.
+     */
+    cli_data_quality: "clean" | "flagged_instrument" | "flagged_late" | "flagged_other" | "missing";
+    /**
+     * 00:00 local time on observation_date converted to UTC; for sort/join only
+     */
+    event_time: string;
+    /**
+     * local climate day per NWS convention (no timezone applied to the date itself)
+     */
+    observation_date: string;
+    /**
+     * units: inches
+     */
+    precipitation_in?: null | number;
+    /**
+     * parsed from CLI product header (_climate.py::_parse_product_timestamp)
+     */
+    product_release_time: string;
+    /**
+     * preliminary | final | correction; dedup priority preliminary < final < correction
+     */
+    report_type: "correction" | "final" | "preliminary";
+    /**
+     * provisional | final | superseded. Kalshi NHIGH/NLOW settlement contractually requires 'final'; 'provisional' values are kept for early-look research only.
+     */
+    settlement_finality: "final" | "provisional" | "superseded";
+    /**
+     * units: inches
+     */
+    snowfall_in?: null | number;
+    /**
+     * ICAO/ASOS station ID
+     */
+    station: string;
+    /**
+     * IANA timezone for the station (e.g. America/Chicago for KORD). Required for local-climate-day semantics; see §U.
+     */
+    station_tz: string;
+    /**
+     * units: fahrenheit — daily high (uppercase F for consistency with obs imperial mode)
+     */
+    temp_max_F?: null | number;
+    /**
+     * units: fahrenheit — daily low
+     */
+    temp_min_F?: null | number;
+}
+
+interface ObservationLedgerV1 {
+    as_of_time?: null | string;
+    /**
+     * units: celsius
+     */
+    dewpoint_c?: null | number;
+    ingestion_id?: null | string;
+    observation_kind?: "METAR" | "SPECI" | null;
+    /**
+     * Lineage row-quality flag per LINEAGE-01; distinct from qc_status enum slot AND distinct from the obs_qc_status bitmask column per QC-05.
+     */
+    observation_quality?: "clean" | "flagged" | "suspect" | null;
+    observation_type: "METAR" | "SPECI";
+    observed_at: string;
+    parser_name?: "ghcnh" | "iem" | "mostlyright_v1" | "ncei" | null;
+    parser_version?: null | string;
+    provenance?: "legacy" | "reingested" | null;
+    qc_status?: "clean" | "flagged" | "suspect" | null;
+    /**
+     * ncei reserved per D-2.1-09; never written in v0.1.0.
+     */
+    source: "awc" | "ghcnh" | "iem" | "ncei";
+    source_received_at?: null | string;
+    station_code: string;
+    /**
+     * units: celsius
+     */
+    temp_c?: null | number;
+}
+
+interface ObservationQcV1 {
+    as_of_time?: null | string;
+    /**
+     * JSON-serialized detector payload; shape per qc_system.
+     */
+    detector_metadata?: null | string;
+    /**
+     * Observation column the rule evaluated (e.g. temp_c).
+     */
+    field: string;
+    flag: "clean" | "flagged" | "suspect";
+    ingestion_id?: null | string;
+    observation_kind?: "METAR" | "SPECI" | null;
+    observed_at: string;
+    parser_name?: null | string;
+    qc_system: string;
+    qc_version: string;
+    rule_id: string;
+    source: "awc" | "ghcnh" | "iem" | "ncei";
+    station_code: string;
+}
+
+interface StationInfo {
+    code: string | null;
+    ghcnh_id: string | null;
+    icao: string;
+    name: string | null;
+    tz: string;
+    latitude: number | null;
+    longitude: number | null;
+    country: string | null;
+}
+declare const STATIONS: ReadonlyArray<StationInfo>;
+declare const STATION_BY_CODE: ReadonlyMap<string, StationInfo>;
+declare const STATION_BY_ICAO: ReadonlyMap<string, StationInfo>;
+
+declare const OBSERVATION_SOURCE_PRIORITY: Readonly<Record<string, number>>;
+declare const CLIMATE_REPORT_TYPE_PRIORITY: Readonly<Record<string, number>>;
+declare const LIVE_V1_POLICY: {
+    name: string;
+    sourcePriority: Readonly<Record<string, number>>;
+    secondaryKey: ReadonlyArray<string>;
+};
+
+interface QcAlphaRule {
+    rule_id: string;
+    bit_position: number;
+    description: string;
+    field: string;
+}
+declare const QC_ALPHA_RULES: ReadonlyArray<QcAlphaRule>;
+declare const QC_ALPHA_RULES_BY_ID: ReadonlyMap<string, QcAlphaRule>;
+
+/**
+ * Recursively coerce `value` into a JSON-serializable structure.
+ *
+ * Coercion rules (mirrors Python's `to_json_safe`):
+ *  - `null` / `undefined` / `NaN` / `Infinity` / `-Infinity` → `null`
+ *  - `Date` → ISO 8601 UTC string ending in `Z`
+ *  - Numeric / boolean / string scalars pass through (non-finite numbers → null)
+ *  - Arrays + plain objects → recursive (cycles → `{ _cycle: true, value: String(obj) }`)
+ *  - Dict keys MUST be strings; non-string keys throw `TypeError`.
+ *  - Anything else (Symbol, function, class instance without `toJSON`) →
+ *    `{ _repr_only: true, value: String(value) }`.
+ */
+declare function toJsonSafe(value: unknown, seen?: WeakSet<object>): unknown;
+interface TradewindsErrorOptions {
+    errorCode?: string;
+    source?: string | null;
+    requestId?: string | null;
+}
+/**
+ * Base class for all mostlyright structured errors.
+ *
+ * `errorCode` is a stable enum (e.g. "SOURCE_UNAVAILABLE") used by callers /
+ * agents to branch on without parsing message text. `source` is the source id
+ * involved (e.g. "iem.archive") when applicable, and `requestId` correlates a
+ * JSON-RPC / MCP request id when applicable.
+ */
+declare class TradewindsError extends Error {
+    /** Subclass override — the stable string enum surfaced via `errorCode`. */
+    static defaultErrorCode: string;
+    readonly errorCode: string;
+    readonly source: string | null;
+    readonly requestId: string | null;
+    constructor(message?: string, options?: TradewindsErrorOptions);
+    /**
+     * Subclass hook returning the structured attributes for `toDict`.
+     * Values are passed through `toJsonSafe` by `toDict()`, so subclasses
+     * don't need to coerce values themselves.
+     */
+    protected payload(): Record<string, unknown>;
+    /** Return a JSON-safe dict suitable for MCP `error.data`. */
+    toDict(): Record<string, unknown>;
+}
+interface SourceUnavailableErrorOptions extends TradewindsErrorOptions {
+    httpStatus?: number | null;
+    retryable?: boolean;
+    retryAfterS?: number | null;
+    underlying?: string;
+    url?: string | null;
+}
+declare class SourceUnavailableError extends TradewindsError {
+    static defaultErrorCode: string;
+    readonly httpStatus: number | null;
+    readonly retryable: boolean;
+    readonly retryAfterS: number | null;
+    readonly underlying: string;
+    readonly url: string | null;
+    constructor(message?: string, options?: SourceUnavailableErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
+interface SchemaValidationErrorOptions extends TradewindsErrorOptions {
+    schemaId: string;
+    violations?: Array<Record<string, unknown>>;
+    quarantineCount?: number;
+    sampleViolations?: Array<Record<string, unknown>>;
+}
+declare class SchemaValidationError extends TradewindsError {
+    static defaultErrorCode: string;
+    readonly schemaId: string;
+    readonly violations: Array<Record<string, unknown>>;
+    readonly quarantineCount: number;
+    readonly sampleViolations: Array<Record<string, unknown>>;
+    constructor(message: string, options: SchemaValidationErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
+type SourceMismatchRole = "observations" | "forecasts" | "settlement";
+interface SourceMismatchErrorOptions extends TradewindsErrorOptions {
+    schemaSource: string;
+    dataSource: string;
+    role?: SourceMismatchRole | null;
+    catalogWarning?: string | null;
+}
+declare class SourceMismatchError extends TradewindsError {
+    static defaultErrorCode: string;
+    /** Canonical role-name vocabulary (design.md §R). */
+    static readonly VALID_ROLES: ReadonlySet<SourceMismatchRole>;
+    readonly schemaSource: string;
+    readonly dataSource: string;
+    readonly role: SourceMismatchRole | null;
+    readonly catalogWarning: string | null;
+    constructor(message: string, options: SourceMismatchErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
+interface LeakageErrorOptions extends TradewindsErrorOptions {
+    asOf: string;
+    violatingCount: number;
+    sampleViolations?: Array<Record<string, unknown>>;
+}
+declare class LeakageError extends TradewindsError {
+    static defaultErrorCode: string;
+    readonly asOf: string;
+    readonly violatingCount: number;
+    readonly sampleViolations: Array<Record<string, unknown>>;
+    constructor(message: string, options: LeakageErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
+interface TemporalDriftErrorOptions extends TradewindsErrorOptions {
+    schemaId: string;
+    assertedRange: [string, string];
+    violatingRows: number;
+    sampleViolations?: Array<Record<string, unknown>>;
+}
+declare class TemporalDriftError extends TradewindsError {
+    static defaultErrorCode: string;
+    readonly schemaId: string;
+    readonly assertedRange: [string, string];
+    readonly violatingRows: number;
+    readonly sampleViolations: Array<Record<string, unknown>>;
+    constructor(message: string, options: TemporalDriftErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
+interface PayloadTooLargeErrorOptions extends TradewindsErrorOptions {
+    declaredSize: number;
+    limit: number;
+    acceptedModes?: string[];
+}
+declare class PayloadTooLargeError extends TradewindsError {
+    static defaultErrorCode: string;
+    readonly declaredSize: number;
+    readonly limit: number;
+    readonly acceptedModes: string[];
+    constructor(message: string, options: PayloadTooLargeErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
+declare class DeferredMarketError extends TradewindsError {
+    static defaultErrorCode: string;
+}
+declare class PolymarketEventError extends TradewindsError {
+    static defaultErrorCode: string;
+}
+interface TherminalErrorOptions extends TradewindsErrorOptions {
+    statusCode?: number | null;
+    retryAfter?: number | null;
+}
+/**
+ * Base HTTP-layer marker. Subclass of `TradewindsError` so callers that
+ * catch `TradewindsError` also catch transport errors.
+ */
+declare class TherminalError extends TradewindsError {
+    static defaultErrorCode: string;
+    readonly statusCode: number | null;
+    constructor(message: string, options?: TherminalErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
+declare class NotFoundError extends TherminalError {
+    static defaultErrorCode: string;
+    constructor(message?: string, options?: TherminalErrorOptions);
+}
+interface RateLimitErrorOptions extends TherminalErrorOptions {
+    retryAfter?: number | null;
+}
+declare class RateLimitError extends TherminalError {
+    static defaultErrorCode: string;
+    readonly retryAfter: number | null;
+    constructor(retryAfter?: number | null, options?: RateLimitErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
+declare class ValidationError extends TherminalError {
+    static defaultErrorCode: string;
+    constructor(message?: string, options?: TherminalErrorOptions);
+}
+declare class AuthenticationError extends TherminalError {
+    static defaultErrorCode: string;
+    constructor(message?: string, options?: TherminalErrorOptions);
+}
+declare class ForbiddenError extends TherminalError {
+    static defaultErrorCode: string;
+    constructor(message?: string, options?: TherminalErrorOptions);
+}
+declare class ServerError extends TherminalError {
+    static defaultErrorCode: string;
+    constructor(message?: string, options?: TherminalErrorOptions);
+}
+/**
+ * Base class for `mostlyright.live.stream` / `live.latest` failures.
+ *
+ * Mirrors Python `LiveStreamError`. Live-streaming errors are a separate
+ * sub-tree from `SourceUnavailableError` because the recovery path differs —
+ * `stream()` swallows empty-tick errors and waits for the next polite-floor
+ * cycle. Only `latest()` raises `NoLiveDataError` on empty responses.
+ */
+declare class LiveStreamError extends TradewindsError {
+    static defaultErrorCode: string;
+}
+interface NoLiveDataErrorOptions extends TradewindsErrorOptions {
+    station: string;
+    source: string;
+}
+/**
+ * `mostlyright.live.latest` returned no observations for the station.
+ *
+ * Carries the resolved ICAO `station` and the canonical source identity
+ * tag (`"awc.live"` / `"iem.live"`) so caller logs can branch by source
+ * without re-parsing the message.
+ */
+declare class NoLiveDataError extends LiveStreamError {
+    static defaultErrorCode: string;
+    readonly station: string;
+    constructor(message: string | undefined, options: NoLiveDataErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
+
+declare const _STATION_TZ: Readonly<Record<string, string>>;
+/** Reference UTC moment in January (no DST in Northern Hemisphere US). */
+declare const _JAN_REF: Date;
+/** NWS CLI typical publication delay: 10 h after midnight LST. */
+declare const _CLI_PUBLICATION_DELAY_HOURS = 10;
+/** Kalshi market typical close time (LST). */
+declare const _MARKET_CLOSE_HOUR_LST = 16;
+declare const _MARKET_CLOSE_MINUTE_LST = 30;
+/**
+ * Return the LOCAL STANDARD TIME UTC offset (in hours) for an IANA tz,
+ * sampled from January 15 2024 12:00 UTC so the result is never affected
+ * by DST in the Northern Hemisphere.
+ *
+ * Implementation: format `_JAN_REF` in the target tz via Intl.DateTimeFormat
+ * and diff against the UTC formatted view to recover the offset.
+ */
+declare function _lstOffsetHours(stationTz: string): number;
+/**
+ * Resolve a station code (NWS 3-letter, ICAO 4-letter) to an IANA tz string.
+ * Honors `tzOverride` first, then the built-in `_STATION_TZ` map.
+ * Throws if no tz can be resolved.
+ */
+declare function _resolveStationTz(station: string, tzOverride?: string): string;
+/**
+ * Return the Kalshi settlement date (YYYY-MM-DD LST) for a UTC moment.
+ *
+ * Kalshi NHIGH/NLOW contracts cover midnight–midnight LOCAL STANDARD TIME.
+ * DST is ignored: the window is always fixed to the standard UTC offset.
+ */
+declare function settlementDateFor(asOf: Date | string, station: string, tzOverride?: string): string;
+/**
+ * Return UTC start/end of the Kalshi settlement window for a date.
+ * The window is midnight-midnight LST, expressed in UTC.
+ */
+declare function settlementWindowUtc(dateStr: string, station: string, tzOverride?: string): [Date, Date];
+/**
+ * Return the UTC time at which the NWS CLI for a date is expected to be
+ * available. Default delay is 10 h after midnight LST on the next day.
+ */
+declare function cliAvailableAt(dateStr: string, station: string, delayHours?: number, tzOverride?: string): Date;
+/**
+ * Return the UTC time of the Kalshi market close for a settlement date.
+ * Kalshi NHIGH/NLOW markets close at 4:30 PM LST on the day of settlement.
+ */
+declare function marketCloseUtc(dateStr: string, station: string, tzOverride?: string): Date;
+
+interface FetchWithRetryOptions {
+    /** Base backoff delay in milliseconds (default 1000). */
+    baseDelayMs?: number;
+    /** Total attempts (default 3). */
+    maxRetries?: number;
+    /** Per-attempt timeout in milliseconds (default 60_000). */
+    timeoutMs?: number;
+    /** Statuses that trigger a retry. Default {429, 500, 502, 503, 504}. */
+    retryStatuses?: ReadonlySet<number>;
+    /** Caller-supplied abort signal (composed with per-attempt timeout). */
+    signal?: AbortSignal;
+    /** Request headers. */
+    headers?: Record<string, string>;
+    /** Convenience: set the User-Agent header. */
+    userAgent?: string;
+    /** HTTP method (default GET). */
+    method?: string;
+    /** Optional request body (forwarded to `fetch`). */
+    body?: BodyInit | null;
+}
+/**
+ * GET (or other) a URL with exponential-backoff retry semantics.
+ *
+ * Behaviour:
+ *  - `signal` is composed with a per-attempt timeout via `AbortController`.
+ *  - On retryable status (default: 429/500/502/503/504), wait
+ *    `baseDelayMs * 2^attempt` (with ≤25% jitter) and retry, up to
+ *    `maxRetries` total attempts.
+ *  - On 404 → `NotFoundError`. On 400/401/403 → `ValidationError` /
+ *    `AuthenticationError` / `ForbiddenError`. After retry exhaustion on
+ *    429 → `RateLimitError` (with `retryAfter` honoured). After retry
+ *    exhaustion on 5xx → `ServerError`.
+ *  - On network/transport failure: retried under the same budget, last
+ *    error rethrown as a `TherminalError` if it isn't one already.
+ */
+declare function fetchWithRetry(url: string, opts?: FetchWithRetryOptions): Promise<Response>;
+
+declare const version = "0.0.0";
+declare function helloCore(): string;
+
+export { AuthenticationError, CLIMATE_REPORT_TYPE_PRIORITY, DeferredMarketError, type FetchWithRetryOptions, ForbiddenError, type ForecastIemMosV1, LIVE_V1_POLICY, LeakageError, type LeakageErrorOptions, LiveStreamError, NoLiveDataError, type NoLiveDataErrorOptions, NotFoundError, OBSERVATION_SOURCE_PRIORITY, type ObservationLedgerV1, type ObservationQcV1, type ObservationV1, PayloadTooLargeError, type PayloadTooLargeErrorOptions, PolymarketEventError, QC_ALPHA_RULES, QC_ALPHA_RULES_BY_ID, type QcAlphaRule, RateLimitError, type RateLimitErrorOptions, STATIONS, STATION_BY_CODE, STATION_BY_ICAO, SchemaValidationError, type SchemaValidationErrorOptions, ServerError, type SettlementCliV1, SourceMismatchError, type SourceMismatchErrorOptions, type SourceMismatchRole, SourceUnavailableError, type SourceUnavailableErrorOptions, type StationInfo, TemporalDriftError, type TemporalDriftErrorOptions, TherminalError, type TherminalErrorOptions, TradewindsError, type TradewindsErrorOptions, ValidationError, _CLI_PUBLICATION_DELAY_HOURS, _JAN_REF, _MARKET_CLOSE_HOUR_LST, _MARKET_CLOSE_MINUTE_LST, _STATION_TZ, _lstOffsetHours, _resolveStationTz, cliAvailableAt, fetchWithRetry, helloCore, marketCloseUtc, settlementDateFor, settlementWindowUtc, toJsonSafe, version };