@mostlyrightmd/economy

Classes

EconomyTickerError

Raised when a ticker is not a string or matches no routing root.

A named subclass (mirrors the NHIGH/NLOW ContractIdError) so callers can instanceof-check rather than parse the message. Mirrors the Python TypeError / ValueError distinction with a single explicit error — an unroutable ticker is NEVER a silent null return.

Extends

ContractError

Constructors

new EconomyTickerError()

new EconomyTickerError(message): EconomyTickerError

Parameters

message

string

Returns

EconomyTickerError

Overrides

ContractError.constructor

Interfaces

DivergenceWarning

A machine-readable divergence event — emitted (and passed to onDivergence) when a TE-settled series ships the agency first-print proxy. Mirrors the Python DivergenceWarning intent: the consumer knows the pair’s value is the agency proxy, NOT the (unlicensed) Trading Economics settlement truth.

Properties

contract

readonly contract: string

The matched Kalshi series root (e.g. "KXUSPPI").

indicator

readonly indicator: string

The economy indicator id.

message

readonly message: string

Human-readable message.

settlementAuthority

readonly settlementAuthority: string

The contractual settlement authority ("TradingEconomics").

EconomyObservationsV1

Properties

indicator

indicator: string

knowledge_time

knowledge_time: string

leakage cutoff; equals vintage_time for economy (research_economy wires leakage on this)

period

period: string

observation period the value refers to: ‘2026-06’ monthly, ‘2026Q2’ quarterly, ‘2026-06-28’ weekly/date, or FOMC meeting date

release_datetime?

optional release_datetime: null | string

wall-clock the value was released (8:30 ET etc.), UTC

release_type

release_type: "final" | "preliminary" | "second" | "advance" | "benchmark" | "revised" | "third"

released_value?

optional released_value: null | number

released numeric value; nullable — a not-yet-released period may be schema-shaped but valueless

retrieved_at?

optional retrieved_at: null | string

provenance of the fetch, UTC

series_id?

optional series_id: null | string

upstream series identifier (BLS/FRED/BEA code) when applicable

settlement_grade

settlement_grade: boolean

is this vintage the settlement truth (first print as-of expiration); False for later vintages AND the 48 TE-settled series

source

source: string

per-row source identity == df.attrs[‘source’]; one of ECONOMY_SOURCES

units?

optional units: null | string

index | percent | thousands_persons | percent_saar | …

vintage_time

vintage_time: string

WHEN this value became known (ALFRED realtime_start / release-day capture); the leakage knowledge_time

EconomyPairRow

A settlement pair — the first-print observation row plus the resolved market-outcome metadata. The CONTRACT-level grade is written to BOTH the canonical snake_case schema field settlement_grade (overwriting the inherited agency vintage grade — C3) and its camelCase alias settlementGrade; both read false for a TE-settled series even though the agency first print is a real vintage. It is the honest label a model reads to know whether the value IS the settlement truth. knowledge_time (= vintage_time) is the leakage cutoff.

Extends

EconomyObservationRow

Properties

agency

readonly agency: string

The resolved settlement agency short name.

contract

readonly contract: string

The matched Kalshi series ROOT ticker.

indicator

indicator: string

Inherited from

EconomyObservationRow.indicator

knowledge_time

knowledge_time: string

leakage cutoff; equals vintage_time for economy (research_economy wires leakage on this)

Inherited from

EconomyObservationRow.knowledge_time

period

period: string

observation period the value refers to: ‘2026-06’ monthly, ‘2026Q2’ quarterly, ‘2026-06-28’ weekly/date, or FOMC meeting date

Inherited from

EconomyObservationRow.period

release_datetime?

optional release_datetime: null | string

wall-clock the value was released (8:30 ET etc.), UTC

Inherited from

EconomyObservationRow.release_datetime

release_type

release_type: "final" | "preliminary" | "second" | "advance" | "benchmark" | "revised" | "third"

Inherited from

EconomyObservationRow.release_type

released_value?

optional released_value: null | number

released numeric value; nullable — a not-yet-released period may be schema-shaped but valueless

Inherited from

EconomyObservationRow.released_value

retrieved_at?

optional retrieved_at: null | string

provenance of the fetch, UTC

Inherited from

EconomyObservationRow.retrieved_at

series_id?

optional series_id: null | string

upstream series identifier (BLS/FRED/BEA code) when applicable

Inherited from

EconomyObservationRow.series_id

settlement_grade

settlement_grade: boolean

is this vintage the settlement truth (first print as-of expiration); False for later vintages AND the 48 TE-settled series

Inherited from

EconomyObservationRow.settlement_grade

settlementGrade

readonly settlementGrade: boolean

Contract-level settlement grade (false for TE-settled series) — a camelCase alias of the canonical settlement_grade; both carry the same value.

source

source: string

per-row source identity == df.attrs[‘source’]; one of ECONOMY_SOURCES

Inherited from

EconomyObservationRow.source

units?

optional units: null | string

index | percent | thousands_persons | percent_saar | …

Inherited from

EconomyObservationRow.units

vintage_time

vintage_time: string

WHEN this value became known (ALFRED realtime_start / release-day capture); the leakage knowledge_time

Inherited from

EconomyObservationRow.vintage_time

EconomyResolution

A resolved Kalshi economy settlement mapping.

Mirrors the Python EconomyResolution fields (camelCase). contractTermsUrl is derived from the routing rule’s contractTermsPdf basename (the trusted routing companion to the agency NAME).

Properties

agency

readonly agency: string

Canonical settlement agency short name (BLS / BEA / DOL / FederalReserve / TradingEconomics).

contractTermsUrl

readonly contractTermsUrl: null | string

The CFTC contract-terms PDF URL for the series, when known.

indicator

readonly indicator: string

Economy indicator id (schema.economy.observations.v1 vocabulary).

root

readonly root: string

The matched Kalshi series ROOT ticker (e.g. "KXUSPPIYOY").

settlementGrade

readonly settlementGrade: boolean

true when the agency first print IS the settlement truth; false for the Trading-Economics-settled series (the agency first print ships as a labeled proxy — a TE value is NEVER fabricated).

EconomySettlementRule

Properties

agency

readonly agency: string

contractTermsPdf

readonly contractTermsPdf: string

indicator

readonly indicator: string

settlementGrade

readonly settlementGrade: boolean

ReleaseEvent

One scheduled release of an economy indicator.

Properties

agency

readonly agency: string

The source agency short name (BLS / BEA / DOL / FederalReserve).

indicator

readonly indicator: string

The economy indicator id.

period

readonly period: string

The observation period this release publishes ("2026-06" / "2026Q2" / a date).

releaseDatetime

readonly releaseDatetime: string

The scheduled release wall-clock, tz-aware UTC ISO (8:30 ET → 12:30 UTC).

ResearchEconomyOptions

Properties

asOf?

optional asOf: TimePoint

Optional leakage cutoff. When given, any pair whose knowledge_time (vintage_time) is after asOf throws LeakageError — a future revision can never leak into research.

delivery?

optional delivery: EconomyDelivery

Where the computation runs (contract §2), forwarded to series. "live" (default) | "hosted" (reserved seam → SourceUnavailableError).

fetchRows?

optional fetchRows: FetchRows

Injected fetcher (tests / custom transport), forwarded to series.

onDivergence()?

optional onDivergence: (warning) => void

Optional structured divergence handler. Invoked with the DivergenceWarning for a TE-settled series so a consumer can branch programmatically. This is the ONLY divergence side-channel — researchEconomy writes nothing to the console (L1); a consumer that wants a log emits one here.

Parameters

warning

DivergenceWarning

Returns

void

source?

optional source: EconomySource

Provenance pin (source-identity contract §1), forwarded to the underlying series read. undefined (default) uses the per-indicator default routing; an unknown source or a valid authority that cannot serve the resolved indicator throws pre-fetch. Whether to also add an includeEconomy covariate seam to core’s dataset() is an OPTION-B question deferred to review — this function does NOT touch core.

SeriesOptions

Properties

delivery?

optional delivery: EconomyDelivery

Where the computation runs (contract §2). "live" (default) hits the public agency APIs; "hosted" is the reserved precomputed-API seam and throws SourceUnavailableError naming MOSTLYRIGHT_ECONOMY_HOSTED_URL + MOSTLYRIGHT_API_KEY.

fetchRows?

optional fetchRows: FetchRows

Injected fetcher (tests / custom transport). When omitted, the default agency dispatch (BLS latest-revised + ALFRED first-print) is used — the live path exercised in the smoke.

signal?

optional signal: AbortSignal

Caller abort signal, propagated to every agency fetch (and composed with each attempt’s retry backoff wait). An abort mid-flight rejects promptly with the platform AbortError — never reclassified as a transport error. Ignored when fetchRows is injected (the caller owns that transport).

source?

optional source: EconomySource

Provenance pin (contract §1). undefined (default) uses the per-indicator default routing; a pin names the authority. An unknown source, OR a valid authority that cannot serve indicator (e.g. source: "bea" for "cpi"), throws BEFORE any fetch — never a silent fallback.

vintages?

optional vintages: Vintages

"settlement" (default) → settlement-grade first-print rows; "all" → every vintage.

SnapshotOptions

Properties

asOf?

optional asOf: Date

The knowledge-time cutoff. Only vintages whose vintage_time is at or before asOf are considered. Defaults to now — the current settlement-target state.

delivery?

optional delivery: EconomyDelivery

Where the computation runs (contract §2), forwarded to series.

fetchRows?

optional fetchRows: FetchRows

Injected fetcher (tests / custom transport), forwarded to series.

indicator

indicator: string

The indicator id (schema.economy.observations.v1 vocabulary).

source?

optional source: EconomySource

Provenance pin (contract §1), forwarded to series.

Type Aliases

EconomyDelivery

EconomyDelivery: "live" | "hosted"

Accepted delivery= values (contract §2).

EconomyObservationRow

EconomyObservationRow: EconomyObservationsV1

One economic-indicator observation row (a schema.economy.observations.v1 record).

EconomySource

EconomySource: "fred" | "bls" | "bea" | "dol" | "fed"

Accepted source= provenance authorities (contract §1).

FetchRows()

FetchRows: (indicator, fromDate, toDate) => Promise<EconomyObservationRow[]>

A function that returns the raw schema.economy.observations.v1 rows for a window.

Parameters

indicator

string

fromDate

Date

toDate

Date

Returns

Promise<EconomyObservationRow[]>

HistoryOptions

HistoryOptions: SeriesOptions

Back-compat alias — history accepts the same options as series.

Vintages

Vintages: "settlement" | "all"

Vintage-selection mode.

Variables

ECONOMY_AGENCY_NAMES

const ECONOMY_AGENCY_NAMES: ReadonlyArray<string>

FEDS_FIRST_CONTRACT

const FEDS_FIRST_CONTRACT: Readonly<Record<string, string>>

FEDS-2026-010 Table 1 first-contract dates (YYYY-MM-DD), keyed on the economy indicator vocabulary. A request below a key’s date is out-of-range. PPI / CPI-Core / jobless-claims floors are Kalshi-inception-derived (not FEDS Table-1 rows), conservatively aligned to the nearest FEDS-dated BLS analog — matching the Python table exactly (tighten if a dated first contract is later confirmed).

FRED_SERIES_BY_INDICATOR

const FRED_SERIES_BY_INDICATOR: Readonly<Record<string, string>>

SETTLEMENT_ROUTING

const SETTLEMENT_ROUTING: Readonly<Record<string, EconomySettlementRule>>

version

const version: "1.9.9" = "1.9.9"

Public package version; kept in lockstep with package.json.

Functions

assertWithinFloor()

assertWithinFloor(indicator, fromDate): void

Throw DataAvailabilityError (reason: "out_of_window") when fromDate predates indicator’s FEDS first-contract floor, or when indicator is unknown (never silently passes). Returns void when fromDate is at/after the floor. Mirrors the Python assert_within_floor.

Parameters

indicator

string

An economy indicator key (must be a key of FEDS_FIRST_CONTRACT).

fromDate

Date

The inclusive start of the requested research range (compared at UTC-day granularity — the time component is dropped).

Returns

void

history()

history(indicator, fromDate, toDate, options): Promise<DataResult<EconomyObservationsV1>>

Deprecated alias of series — returns byte-identical output.

Parameters

indicator

string

fromDate

Date

toDate

Date

options

SeriesOptions = {}

Returns

Promise<DataResult<EconomyObservationsV1>>

Deprecated

Use series. history is retained as a working alias (plan conformed the economy surface to the cross-vertical source-identity contract). It emits NO runtime warning this release — matching the research/dataset silent-alias style. A deprecation lands in the next minor; removal at 2.0. All arguments forward verbatim to series; see its docs for the full contract (vintages, source, delivery).

kalshiEconomyResolve()

kalshiEconomyResolve(seriesTicker): EconomyResolution

Resolve a Kalshi economy ticker to its (root, settlement mapping).

Matching is exact-then-longest-prefix (identical to the Python resolver):

Exact match on the full (uppercased) ticker, else
the LONGEST SETTLEMENT_ROUTING root that ticker starts with.

Parameters

seriesTicker

string

A Kalshi economy series root ("KXCPIYOY") or a concrete dated market ticker ("KXCPIYOY-26JUL"). Case-insensitive.

Returns

EconomyResolution

A frozen EconomyResolution.

Throws

seriesTicker is not a string, or matches no root.

releases()

releases(indicator): ReleaseEvent[]

Return the release calendar / schedule for indicator, sorted ascending by releaseDatetime. Sourced from the curated v1 schedule table (a live agency-calendar fetch is a documented fast-follow).

Parameters

indicator

string

Returns

ReleaseEvent[]

Throws

indicator is not a string.

Throws

indicator has no known schedule (never returns []/null).

researchEconomy()

researchEconomy(seriesOrContract, fromDate, toDate, options): Promise<EconomyPairRow[]>

Return leakage-free settlement pairs for seriesOrContract.

Each pair joins the market outcome (resolved agency/indicator/settlement metadata) to the first-print indicator value and the as-of features known at knowledge_time = vintage_time — safe in research and live.

Parameters

seriesOrContract

string

A Kalshi economy series root ("KXCPIYOY") or a concrete dated market ticker ("KXCPIYOY-26JUL"). Case-insensitive.

fromDate

Date

Inclusive start of the requested range.

toDate

Date

Inclusive end of the requested range.

options

ResearchEconomyOptions = {}

asOf (leakage cutoff), fetchRows, onDivergence.

Returns

Promise<EconomyPairRow[]>

The settlement pairs (object array — no DataFrame).

Throws

the ticker resolves to no routing root.

Throws

the indicator’s window is below the FEDS floor.

Throws

the settlement period has no first print yet.

Throws

an asOf was given and a pair’s vintage_time is after it.

series()

series(indicator, fromDate, toDate, options): Promise<DataResult<EconomyObservationsV1>>

Return economic-indicator observation rows for indicator (canonical read).

Parameters

indicator

string

The indicator id (schema.economy.observations.v1 vocabulary: "cpi" / "nfp" / "gdp" / "ppi" / "jobless_claims" / …).

fromDate

Date

Inclusive start of the requested range.

toDate

Date

Inclusive end of the requested range.

options

SeriesOptions = {}

vintages ("settlement" default | "all"), source (contract §1 pin), delivery (contract §2), + an optional injected fetchRows.

Returns

Promise<DataResult<EconomyObservationsV1>>

The observation rows (object array — the TS SDK convention; no DataFrame).

Throws

vintages/source/delivery is invalid (source/delivery validated BEFORE any fetch).

Throws

delivery: "hosted" (the reserved seam).

Throws

fromDate is below the indicator’s FEDS floor, or the indicator is unknown.

Throws

the window has no relevant rows — a scheduled release has not landed yet. NEVER returns []/null.

snapshot()

snapshot(options): Promise<DataResult<EconomyObservationsV1>>

Return the settlement-target state of indicator as knowable at asOf.

Parameters

options

SnapshotOptions

indicator (required), asOf (default now), source, delivery, fetchRows.

Returns

Promise<DataResult<EconomyObservationsV1>>

The { rows, provenance } envelope (the same DataResult<Row> series/history return): one settlement-grade row per period knowable at asOf (the latest such vintage per period), with provenance byte-identical to the composed series read (same schema_id, source stamped from the rows).

Throws

an invalid source/delivery (pre-fetch) — see series.

Throws

delivery: "hosted" (the reserved seam).

Throws

indicator is unknown (no FEDS floor).

Throws

nothing is knowable at asOf — no settlement-grade vintage exists at or before the cutoff. NEVER returns []/null.