@mostlyrightmd/weather/hosted

Interfaces

SatelliteHostedOptions

Properties

apiKey

readonly apiKey: string

The MOSTLYRIGHT_API_KEY sent as x-api-key. Required.

fetchImpl?

readonly optional fetchImpl: FetchLike

Injectable fetch (tests). Default: the browser/MV3 global.

fromTime

readonly fromTime: string

Event-time window start (ISO-8601).

hostedUrl

readonly hostedUrl: string

The weather serving base URL (MOSTLYRIGHT_WEATHER_HOSTED_URL) — the deployed mr-serving origin. Required; a missing value throws HostedConfigError. In the MV3 extension this is build-injected.

lat?

readonly optional lat: number

Latitude of a coordinate site, in decimal degrees. Given together with lon, addresses an arbitrary point that need not exist in any station registry; the site id is derived client-side by deriveSiteId and sent as the single station= parameter, so the wire contract is unchanged. Supplying only one of lat/lon throws before any fetch.

lon?

readonly optional lon: number

Longitude of a coordinate site, in decimal degrees (negative = west). See SatelliteHostedOptions.lat.

product?

readonly optional product: string

Optional product id; omit for the server’s per-source default product.

retrievedAt?

readonly optional retrievedAt: string

Retrieval timestamp override (ISO-8601 UTC). Default: now.

satellite

readonly satellite: string

Explicit satellite id (e.g. "goes16"). Required: the hosted /satellite endpoint does not auto-route (unlike the Python satellite() dispatch, which resolves the family client-side before the hosted call), so the browser shim must name the family or the server returns 422.

signal?

readonly optional signal: AbortSignal

Optional AbortSignal for cancellation.

siteId?

readonly optional siteId: string

Override the derived identity of a coordinate site. Coordinate mode only. It must be the digit-bearing coordinate form: a letter-only / ICAO-shaped value is refused before any fetch, mirroring Python’s reserved-identifier rule, because identity is what selects the partition — an accepted siteId: "KNYC" beside unrelated coordinates would read KNYC’s own partition.

station?

readonly optional station: string | readonly string[]

Single station or a list (ICAO codes, or any site id the fleet has written). Mutually exclusive with lat/lon: exactly one identity form must be supplied, and supplying both — or neither — throws before any fetch. Optional in the type only; the rule is enforced in code.

timezone?

readonly optional timezone: string

IANA timezone for a coordinate site, carried as caller-supplied metadata. Coordinate mode only. It is not sent on the wire and not resolved from the coordinates: doing either would need a geo lookup the browser bundle does not ship.

toTime

readonly toTime: string

Event-time window end (ISO-8601).

variable?

readonly optional variable: string

Optional single-variable filter.

---

SatelliteRow

A canonical satellite row emitted by satelliteHosted. Mirrors the Python satellite(...) DataFrame row (snake_case wire keys → camelCase props). Field presence follows the wire row: a genuine extracted row carries every field; a qc_status="suspect" sentinel row, which Python emits when the units contract fails, carries empty scan times and pixelRow=-1.

Properties

asOfTime

readonly asOfTime: null | string

RFC3339-Z knowledge-time string echoed by the server, or null.

delivery

readonly delivery: "hosted"

Delivery channel lineage — always "hosted" on this path.

eventTime

readonly eventTime: null | string

Event time (scan start), ISO-8601 UTC, or null.

ingestedAt

readonly ingestedAt: null | string

knowledgeTime

readonly knowledgeTime: null | string

Knowledge time (leakage anchor), ISO-8601 UTC, or null.

pixelCol

readonly pixelCol: null | number

pixelDataQualityFlag

readonly pixelDataQualityFlag: null | number

pixelRow

readonly pixelRow: null | number

pixelValue

readonly pixelValue: null | number

pressureLevelHpa

readonly pressureLevelHpa: null | number

product

readonly product: string

qcStatus

readonly qcStatus: string

retrievedAt

readonly retrievedAt: string

When the SDK retrieved the row (ISO-8601 UTC).

satellite

readonly satellite: string

scanEndUtc

readonly scanEndUtc: null | string

Byte-faithful RFC3339-Z scan-end string, or null.

scanStartUtc

readonly scanStartUtc: null | string

Byte-faithful RFC3339-Z scan-start string (event time), or null.

source

readonly source: string

Satellite family identity — passed through verbatim, never re-derived.

sourceObjectKey

readonly sourceObjectKey: string

station

readonly station: string

stationLat

readonly stationLat: null | number

stationLon

readonly stationLon: null | number

subsatelliteLongitudeDegrees

readonly subsatelliteLongitudeDegrees: null | number

units

readonly units: string

variable

readonly variable: string

Type Aliases

SatelliteSourceIdentity

SatelliteSourceIdentity: typeof SATELLITE_SOURCE_IDENTITIES[number]

Variables

SATELLITE_SOURCE_IDENTITIES

const SATELLITE_SOURCE_IDENTITIES: readonly ["noaa_goes", "jma_himawari", "noaa_viirs", "eumetsat_meteosat"]

The satellite family source identities the hosted rows carry — one identity per instrument family. Informational: the shim passes source through verbatim and never re-derives it.

Functions

projectSatelliteRow()

projectSatelliteRow(raw, retrievedAt): SatelliteRow

Project one wire row into a canonical SatelliteRow, or throw.

Nothing is defaulted. Turning a missing identity into "", a missing number into null, or a missing qc_status into "clean" would synthesise a verdict the server never sent, so a QC-suspect row that lost its verdict in transit would read as clean. Python validates hosted frames against schema.satellite.v1; this is the browser’s equivalent, kept compact rather than generated (the satellite schemas have no generated validator).

Parameters

raw

unknown

retrievedAt

string

Returns

SatelliteRow

Throws

a non-object row, a missing/blank required identity field, or a qc_status outside the schema enum.

---

satelliteHosted()

satelliteHosted(options): Promise<readonly SatelliteRow[]>

Fetch satellite rows from the hosted weather serving /satellite endpoint.

The TS mirror of the Python satellite(delivery="hosted", ...): GETs ${MOSTLYRIGHT_WEATHER_HOSTED_URL}/satellite?... with the MOSTLYRIGHT_API_KEY header and returns rows byte-identical to the Python hosted contract. The source family identity is passed through verbatim; delivery is "hosted".

Pass either station (a code or site id, or a list) or lat+lon (a coordinate site, resolved to a site id client-side). Supplying both, only one of lat/lon, or neither throws before any fetch — identity selects which partition is read, so an ambiguous request must never reach the network.

MV3-safe: fetch + JSON only (via hostedFetchJson). No Node APIs.

Parameters

options

SatelliteHostedOptions

Returns

Promise<readonly SatelliteRow[]>

Throws

conflicting or incomplete identity options, an out-of-range or non-finite coordinate, a malformed site id, or an ICAO-shaped explicit siteId in coordinate mode — all before any network call.

Throws

when MOSTLYRIGHT_WEATHER_HOSTED_URL / MOSTLYRIGHT_API_KEY is missing, or station is supplied but empty — raised before any network call.

Throws

on a non-2xx or non-JSON response (from hostedFetchJson).