@mostlyrightmd/core 1.1.3 → 1.4.0

package/dist/index.d.ts

@@ -82,43 +82,207 @@ interface ObservationV1 {
 }
 
 interface ForecastIemMosV1 {
+    /**
+     * units: celsius
+     */
+    apparent_temp_c?: null | number;
+    /**
+     * units: J/kg
+     */
+    cape_jkg?: null | number;
+    /**
+     * units: percent
+     */
+    cloud_cover_pct?: number | null;
+    /**
+     * units: celsius
+     */
+    dew_point_c?: null | number;
+    /**
+     * units: W/m^2
+     */
+    direct_radiation_wm2?: null | number;
+    /**
+     * units: hours — (valid_at - issued_at).total_seconds() / 3600
+     */
+    forecast_hour: number;
+    /**
+     * units: meters
+     */
+    freezing_level_m?: number | null;
+    /**
+     * model run time (knowledge_time). Nullable to accommodate Phase 20 open_meteo.seamless rows whose cycle is unrecoverable from the response. LeakageDetector + assert_issued_at_populated() are the runtime gates that reject null issued_at in training-data paths.
+     */
+    issued_at?: null | string;
+    /**
+     * e.g. NBE, GFS, LAV, MET, gfs_global, ecmwf_ifs025
+     */
+    model: string;
+    /**
+     * units: probability — bounded [0, 1]
+     */
+    precip_probability?: null | number;
+    /**
+     * units: mm
+     */
+    precipitation_mm?: null | number;
+    /**
+     * units: hPa
+     */
+    pressure_msl_hpa?: null | number;
+    /**
+     * wall-clock time the row was fetched from upstream
+     */
+    retrieved_at: string;
+    /**
+     * units: W/m^2
+     */
+    shortwave_radiation_wm2?: null | number;
+    /**
+     * units: percent — bounded [0, 100]
+     */
+    sky_cover_pct?: number | null;
+    /**
+     * units: meters
+     */
+    snow_depth_m?: null | number;
+    /**
+     * iem.archive | open_meteo.previous_runs | open_meteo.single_run | open_meteo.live
+     */
+    source: string;
+    station: string;
+    /**
+     * units: hPa
+     */
+    surface_pressure_hpa?: null | number;
+    /**
+     * units: celsius
+     */
+    temp_c?: null | number;
+    /**
+     * forecast target time (event_time)
+     */
+    valid_at: string;
+    /**
+     * units: meters
+     */
+    visibility_m?: number | null;
+    /**
+     * units: WMO 4677 — WMO weather code (clear, fog, rain, snow, etc.)
+     */
+    weather_code?: number | null;
+    /**
+     * units: degrees
+     */
+    wind_dir_deg?: number | null;
+    /**
+     * units: m/s
+     */
+    wind_gusts_ms?: null | number;
+    /**
+     * units: m/s
+     */
+    wind_speed_ms?: null | number;
+}
+
+interface ForecastStationV1 {
+    /**
+     * units: celsius
+     */
+    apparent_temp_c?: null | number;
+    /**
+     * units: J/kg
+     */
+    cape_jkg?: null | number;
+    /**
+     * units: percent
+     */
+    cloud_cover_pct?: number | null;
     /**
      * units: celsius
      */
     dew_point_c?: null | number;
+    /**
+     * units: W/m^2
+     */
+    direct_radiation_wm2?: null | number;
     /**
      * units: hours — (valid_at - issued_at).total_seconds() / 3600
      */
     forecast_hour: number;
     /**
-     * model run time (from source `runtime` field)
+     * units: meters
      */
-    issued_at: string;
+    freezing_level_m?: number | null;
     /**
-     * e.g. NBE, GFS, LAV, MET
+     * model run time (knowledge_time). Nullable to accommodate Phase 20 open_meteo.seamless rows whose cycle is unrecoverable from the response. LeakageDetector + assert_issued_at_populated() are the runtime gates that reject null issued_at in training-data paths.
+     */
+    issued_at?: null | string;
+    /**
+     * e.g. NBE, GFS, LAV, MET, gfs_global, ecmwf_ifs025
      */
     model: string;
     /**
      * units: probability — bounded [0, 1]
      */
     precip_probability?: null | number;
+    /**
+     * units: mm
+     */
+    precipitation_mm?: null | number;
+    /**
+     * units: hPa
+     */
+    pressure_msl_hpa?: null | number;
+    /**
+     * wall-clock time the row was fetched from upstream
+     */
+    retrieved_at: string;
+    /**
+     * units: W/m^2
+     */
+    shortwave_radiation_wm2?: null | number;
     /**
      * units: percent — bounded [0, 100]
      */
     sky_cover_pct?: number | null;
+    /**
+     * units: meters
+     */
+    snow_depth_m?: null | number;
+    /**
+     * iem.archive | open_meteo.previous_runs | open_meteo.single_run | open_meteo.live
+     */
+    source: string;
     station: string;
+    /**
+     * units: hPa
+     */
+    surface_pressure_hpa?: null | number;
     /**
      * units: celsius
      */
     temp_c?: null | number;
     /**
-     * forecast target time (from source `ftime`)
+     * forecast target time (event_time)
      */
     valid_at: string;
+    /**
+     * units: meters
+     */
+    visibility_m?: number | null;
+    /**
+     * units: WMO 4677 — WMO weather code (clear, fog, rain, snow, etc.)
+     */
+    weather_code?: number | null;
     /**
      * units: degrees
      */
     wind_dir_deg?: number | null;
+    /**
+     * units: m/s
+     */
+    wind_gusts_ms?: null | number;
     /**
      * units: m/s
      */
@@ -237,6 +401,7 @@ interface StationInfo {
     latitude: number | null;
     longitude: number | null;
     country: string | null;
+    venues: ReadonlyArray<string>;
 }
 declare const STATIONS: ReadonlyArray<StationInfo>;
 declare const STATION_BY_CODE: ReadonlyMap<string, StationInfo>;
@@ -272,7 +437,7 @@ declare const QC_ALPHA_RULES_BY_ID: ReadonlyMap<string, QcAlphaRule>;
  *    `{ _repr_only: true, value: String(value) }`.
  */
 declare function toJsonSafe(value: unknown, seen?: WeakSet<object>): unknown;
-interface TradewindsErrorOptions {
+interface MostlyRightErrorOptions {
     errorCode?: string;
     source?: string | null;
     requestId?: string | null;
@@ -285,13 +450,13 @@ interface TradewindsErrorOptions {
  * involved (e.g. "iem.archive") when applicable, and `requestId` correlates a
  * JSON-RPC / MCP request id when applicable.
  */
-declare class TradewindsError extends Error {
+declare class MostlyRightError 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);
+    constructor(message?: string, options?: MostlyRightErrorOptions);
     /**
      * Subclass hook returning the structured attributes for `toDict`.
      * Values are passed through `toJsonSafe` by `toDict()`, so subclasses
@@ -301,14 +466,14 @@ declare class TradewindsError extends Error {
     /** Return a JSON-safe dict suitable for MCP `error.data`. */
     toDict(): Record<string, unknown>;
 }
-interface SourceUnavailableErrorOptions extends TradewindsErrorOptions {
+interface SourceUnavailableErrorOptions extends MostlyRightErrorOptions {
     httpStatus?: number | null;
     retryable?: boolean;
     retryAfterS?: number | null;
     underlying?: string;
     url?: string | null;
 }
-declare class SourceUnavailableError extends TradewindsError {
+declare class SourceUnavailableError extends MostlyRightError {
     static defaultErrorCode: string;
     readonly httpStatus: number | null;
     readonly retryable: boolean;
@@ -318,13 +483,71 @@ declare class SourceUnavailableError extends TradewindsError {
     constructor(message?: string, options?: SourceUnavailableErrorOptions);
     protected payload(): Record<string, unknown>;
 }
-interface SchemaValidationErrorOptions extends TradewindsErrorOptions {
+/** Shared reason enum — MUST match Python EXACTLY (Phase 21 D-04). */
+declare const DATA_AVAILABILITY_REASONS: readonly ["model_unavailable", "out_of_window", "cache_miss", "source_404", "source_5xx", "rate_limited"];
+type DataAvailabilityReason = (typeof DATA_AVAILABILITY_REASONS)[number];
+interface DataAvailabilityErrorOptions extends MostlyRightErrorOptions {
+    reason: DataAvailabilityReason;
+    hint: string;
+}
+declare class DataAvailabilityError extends MostlyRightError {
+    static defaultErrorCode: string;
+    readonly reason: DataAvailabilityReason;
+    readonly hint: string;
+    constructor(options: DataAvailabilityErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
+interface NwpNotAvailableErrorOptions extends MostlyRightErrorOptions {
+    /** Station the caller asked for (echoed back for log/error attribution). */
+    station: string;
+    /** NWP model the caller asked for (e.g. `"gfs"`, `"hrrr"`). */
+    model: string;
+    /** Operator-actionable hint. Required (matches DataAvailabilityError contract). */
+    hint: string;
+}
+/**
+ * Raised when the TS `forecastNwp()` stub is called.
+ *
+ * **Why this exists:** no production-ready browser GRIB2 decoder ships in
+ * v1.x (eccodes / cfgrib are C/Python only; WASM compile-time + bundle
+ * size make a browser port impractical today). The function signature is
+ * stable so callers can write code today; v2.0+ lands the execution body.
+ *
+ * **Recommended catch pattern:**
+ *
+ * ```ts
+ * import { forecastNwp } from '@mostlyrightmd/weather';
+ * import { NwpNotAvailableError } from '@mostlyrightmd/core';
+ *
+ * try {
+ *   const grid = await forecastNwp('KNYC', 'gfs');
+ * } catch (e) {
+ *   if (e instanceof NwpNotAvailableError) {
+ *     console.warn(`NWP deferred to v2.0+; ${e.hint}`);
+ *     // Fall back to iemMosForecasts() when available, else Python SDK.
+ *   } else {
+ *     throw e;
+ *   }
+ * }
+ * ```
+ *
+ * See [docs/nwp-forecasts.md](https://mostlyright.md/docs/sdk/typescript/nwp-forecasts/)
+ * for the full architectural rationale and the v2.0+ roadmap.
+ */
+declare class NwpNotAvailableError extends DataAvailabilityError {
+    static defaultErrorCode: string;
+    readonly station: string;
+    readonly model: string;
+    constructor(options: NwpNotAvailableErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
+interface SchemaValidationErrorOptions extends MostlyRightErrorOptions {
     schemaId: string;
     violations?: Array<Record<string, unknown>>;
     quarantineCount?: number;
     sampleViolations?: Array<Record<string, unknown>>;
 }
-declare class SchemaValidationError extends TradewindsError {
+declare class SchemaValidationError extends MostlyRightError {
     static defaultErrorCode: string;
     readonly schemaId: string;
     readonly violations: Array<Record<string, unknown>>;
@@ -334,13 +557,13 @@ declare class SchemaValidationError extends TradewindsError {
     protected payload(): Record<string, unknown>;
 }
 type SourceMismatchRole = "observations" | "forecasts" | "settlement";
-interface SourceMismatchErrorOptions extends TradewindsErrorOptions {
+interface SourceMismatchErrorOptions extends MostlyRightErrorOptions {
     schemaSource: string;
     dataSource: string;
     role?: SourceMismatchRole | null;
     catalogWarning?: string | null;
 }
-declare class SourceMismatchError extends TradewindsError {
+declare class SourceMismatchError extends MostlyRightError {
     static defaultErrorCode: string;
     /** Canonical role-name vocabulary (design.md §R). */
     static readonly VALID_ROLES: ReadonlySet<SourceMismatchRole>;
@@ -351,12 +574,12 @@ declare class SourceMismatchError extends TradewindsError {
     constructor(message: string, options: SourceMismatchErrorOptions);
     protected payload(): Record<string, unknown>;
 }
-interface LeakageErrorOptions extends TradewindsErrorOptions {
+interface LeakageErrorOptions extends MostlyRightErrorOptions {
     asOf: string;
     violatingCount: number;
     sampleViolations?: Array<Record<string, unknown>>;
 }
-declare class LeakageError extends TradewindsError {
+declare class LeakageError extends MostlyRightError {
     static defaultErrorCode: string;
     readonly asOf: string;
     readonly violatingCount: number;
@@ -364,13 +587,55 @@ declare class LeakageError extends TradewindsError {
     constructor(message: string, options: LeakageErrorOptions);
     protected payload(): Record<string, unknown>;
 }
-interface TemporalDriftErrorOptions extends TradewindsErrorOptions {
+interface IssuedAtMissingErrorOptions extends MostlyRightErrorOptions {
+    violatingCount?: number;
+    sampleViolations?: Array<Record<string, unknown>>;
+}
+/**
+ * A forecast row would land with `issuedAt = null`.
+ *
+ * Phase 20 OM-04. Origin: Tarabcak/mostlyright#70 — the legacy
+ * seamless-feed bug where `/forecast_series` proxied Open-Meteo's
+ * seamless endpoint without preserving `issued_at`, silently using
+ * post-snapshot model runs in training data.
+ */
+declare class IssuedAtMissingError extends SchemaValidationError {
+    static defaultErrorCode: string;
+    readonly violatingCountRows: number;
+    constructor(message: string, options?: IssuedAtMissingErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
+interface OpenMeteoSeamlessLeakageErrorOptions extends MostlyRightErrorOptions {
+    model: string;
+    endpointUrl: string;
+    asOf?: string | null;
+}
+/**
+ * The Open-Meteo Historical Forecast (seamless) endpoint was used
+ * without `allowLeakage: true`.
+ *
+ * Phase 20 D-01 (locked decision): the seamless endpoint silently
+ * stitches forecasts from multiple model cycles into a continuous
+ * timeseries; the cycle that produced each value is unrecoverable from
+ * the response. `LeakageDetector` rejects rows tagged
+ * `source="open_meteo.seamless"` whenever `as_of` is asserted.
+ *
+ * Origin: Tarabcak/mostlyright#70.
+ */
+declare class OpenMeteoSeamlessLeakageError extends LeakageError {
+    static defaultErrorCode: string;
+    readonly model: string;
+    readonly endpointUrl: string;
+    constructor(message: string, options: OpenMeteoSeamlessLeakageErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
+interface TemporalDriftErrorOptions extends MostlyRightErrorOptions {
     schemaId: string;
     assertedRange: [string, string];
     violatingRows: number;
     sampleViolations?: Array<Record<string, unknown>>;
 }
-declare class TemporalDriftError extends TradewindsError {
+declare class TemporalDriftError extends MostlyRightError {
     static defaultErrorCode: string;
     readonly schemaId: string;
     readonly assertedRange: [string, string];
@@ -379,12 +644,12 @@ declare class TemporalDriftError extends TradewindsError {
     constructor(message: string, options: TemporalDriftErrorOptions);
     protected payload(): Record<string, unknown>;
 }
-interface PayloadTooLargeErrorOptions extends TradewindsErrorOptions {
+interface PayloadTooLargeErrorOptions extends MostlyRightErrorOptions {
     declaredSize: number;
     limit: number;
     acceptedModes?: string[];
 }
-declare class PayloadTooLargeError extends TradewindsError {
+declare class PayloadTooLargeError extends MostlyRightError {
     static defaultErrorCode: string;
     readonly declaredSize: number;
     readonly limit: number;
@@ -392,21 +657,21 @@ declare class PayloadTooLargeError extends TradewindsError {
     constructor(message: string, options: PayloadTooLargeErrorOptions);
     protected payload(): Record<string, unknown>;
 }
-declare class DeferredMarketError extends TradewindsError {
+declare class DeferredMarketError extends MostlyRightError {
     static defaultErrorCode: string;
 }
-declare class PolymarketEventError extends TradewindsError {
+declare class PolymarketEventError extends MostlyRightError {
     static defaultErrorCode: string;
 }
-interface TherminalErrorOptions extends TradewindsErrorOptions {
+interface TherminalErrorOptions extends MostlyRightErrorOptions {
     statusCode?: number | null;
     retryAfter?: number | null;
 }
 /**
- * Base HTTP-layer marker. Subclass of `TradewindsError` so callers that
- * catch `TradewindsError` also catch transport errors.
+ * Base HTTP-layer marker. Subclass of `MostlyRightError` so callers that
+ * catch `MostlyRightError` also catch transport errors.
  */
-declare class TherminalError extends TradewindsError {
+declare class TherminalError extends MostlyRightError {
     static defaultErrorCode: string;
     readonly statusCode: number | null;
     constructor(message: string, options?: TherminalErrorOptions);
@@ -449,10 +714,10 @@ declare class ServerError extends TherminalError {
  * `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 {
+declare class LiveStreamError extends MostlyRightError {
     static defaultErrorCode: string;
 }
-interface NoLiveDataErrorOptions extends TradewindsErrorOptions {
+interface NoLiveDataErrorOptions extends MostlyRightErrorOptions {
     station: string;
     source: string;
 }
@@ -466,7 +731,7 @@ interface NoLiveDataErrorOptions extends TradewindsErrorOptions {
 declare class NoLiveDataError extends LiveStreamError {
     static defaultErrorCode: string;
     readonly station: string;
-    constructor(message: string | undefined, options: NoLiveDataErrorOptions);
+    constructor(message: string, options: NoLiveDataErrorOptions);
     protected payload(): Record<string, unknown>;
 }
 
@@ -516,6 +781,38 @@ declare function cliAvailableAt(dateStr: string, station: string, delayHours?: n
  */
 declare function marketCloseUtc(dateStr: string, station: string, tzOverride?: string): Date;
 
+type Station = StationInfo;
+/**
+ * Read-only view over the station registry with venue/country filters.
+ *
+ * Lookups accept either the registry code (3-letter NWS code for US stations,
+ * ICAO for international) or the 4-letter ICAO directly, so `get("NYC")`,
+ * `get("KNYC")`, and `get("EGLL")` all resolve.
+ */
+declare class StationCatalog {
+    private readonly stations;
+    private readonly byCode;
+    private readonly byIcao;
+    constructor(stations?: ReadonlyArray<Station>);
+    /**
+     * Return the station for `code` (registry code or ICAO).
+     * @throws if no station matches.
+     */
+    get(code: string): Station;
+    /** Stations tagged with `venue` (e.g. "kalshi"), sorted by ICAO. */
+    filterByVenue(venue: string): Station[];
+    /** Stations whose ISO 3166-1 alpha-2 `country` matches, sorted by ICAO. */
+    filterByCountry(country: string): Station[];
+    /** Union of all venue tags present in the catalog. */
+    venues(): ReadonlySet<string>;
+    /** True iff `code` resolves to a station (by registry code or ICAO). */
+    has(code: string): boolean;
+    get size(): number;
+    [Symbol.iterator](): Iterator<Station>;
+}
+/** Process-wide default catalog over the codegen station registry. */
+declare const CATALOG: StationCatalog;
+
 interface FetchWithRetryOptions {
     /** Base backoff delay in milliseconds (default 1000). */
     baseDelayMs?: number;
@@ -567,4 +864,4 @@ 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 };
+export { AuthenticationError, CATALOG, CLIMATE_REPORT_TYPE_PRIORITY, DATA_AVAILABILITY_REASONS, DataAvailabilityError, type DataAvailabilityErrorOptions, type DataAvailabilityReason, DeferredMarketError, type FetchWithRetryOptions, ForbiddenError, type ForecastIemMosV1, type ForecastStationV1, IssuedAtMissingError, type IssuedAtMissingErrorOptions, LIVE_V1_POLICY, LeakageError, type LeakageErrorOptions, LiveStreamError, MostlyRightError, type MostlyRightErrorOptions, NoLiveDataError, type NoLiveDataErrorOptions, NotFoundError, NwpNotAvailableError, type NwpNotAvailableErrorOptions, OBSERVATION_SOURCE_PRIORITY, type ObservationLedgerV1, type ObservationQcV1, type ObservationV1, OpenMeteoSeamlessLeakageError, type OpenMeteoSeamlessLeakageErrorOptions, 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 Station, StationCatalog, type StationInfo, TemporalDriftError, type TemporalDriftErrorOptions, TherminalError, type TherminalErrorOptions, 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 };