@mostlyrightmd/finance
Classes
Section titled “Classes”EarningsContractIdError
Section titled “EarningsContractIdError”Custom error type for earnings contract-id parsing / validation failures.
Mirrors the Python ValueError/TypeError distinction: in TS we use a
named subclass so callers can instanceof-check rather than parse error
messages.
Extends
Section titled “Extends”ContractError
Constructors
Section titled “Constructors”new EarningsContractIdError()
Section titled “new EarningsContractIdError()”new EarningsContractIdError(
message):EarningsContractIdError
Parameters
Section titled “Parameters”message
Section titled “message”string
Returns
Section titled “Returns”Overrides
Section titled “Overrides”ContractError.constructor
EarningsPitError
Section titled “EarningsPitError”Error raised by alignEventDate for a bad event date, an unknown
ticker, or a mis-paired (eventDate, callInstant). A named subclass so
callers can instanceof-check rather than parse error messages.
Extends
Section titled “Extends”ContractError
Constructors
Section titled “Constructors”new EarningsPitError()
Section titled “new EarningsPitError()”new EarningsPitError(
message):EarningsPitError
Parameters
Section titled “Parameters”message
Section titled “message”string
Returns
Section titled “Returns”Overrides
Section titled “Overrides”ContractError.constructor
Interfaces
Section titled “Interfaces”AlignEventDateOptions
Section titled “AlignEventDateOptions”Properties
Section titled “Properties”callInstant?
Section titled “callInstant?”
readonlyoptionalcallInstant:string
Optional ISO-8601 UTC instant of the call. When given, the event date is
re-projected to the HQ-local calendar date of that instant (the ±1-UTC-day
correction) — so a call that straddles a UTC day boundary lands on the
correct local date. The re-projected hq-local date must be within ±1
calendar day of the supplied eventDate; a larger divergence throws (it
signals a mis-paired (eventDate, callInstant)). When omitted, eventDate
is returned unchanged (after coercion).
ConsumeEarningsStreamOptions
Section titled “ConsumeEarningsStreamOptions”Properties
Section titled “Properties”callId
Section titled “callId”
readonlycallId:string
eventSourceFactory?
Section titled “eventSourceFactory?”
readonlyoptionaleventSourceFactory:EventSourceFactory
Opens an EventSource for a URL. Default: new EventSource(url) (browser).
Injectable so non-browser tests can mock it.
mintToken()
Section titled “mintToken()”
readonlymintToken: (ticker,callId) =>Promise<string>
Mints a short-lived signed-URL token via the authenticated path. REQUIRED — a browser EventSource cannot set an Authorization header, so the token is carried on the URL (P2).
Parameters
Section titled “Parameters”ticker
Section titled “ticker”string
callId
Section titled “callId”string
Returns
Section titled “Returns”Promise<string>
ticker
Section titled “ticker”
readonlyticker:string
EarningsCalendarRow
Section titled “EarningsCalendarRow”Properties
Section titled “Properties”callScheduledAt
Section titled “callScheduledAt”callScheduledAt:
string
hqTimezone
Section titled “hqTimezone”hqTimezone:
string
provider
Section titled “provider”provider:
string
ticker
Section titled “ticker”ticker:
string
EarningsResolution
Section titled “EarningsResolution”The frozen tuple a Kalshi earnings-mention contract resolves to.
Mirrors import(”./kalshi-nhigh.js”).NHighResolution: an immutable
(ticker, targetWord, eventDate, resolutionRule) carrier so a resolution
cannot be mutated downstream (the frozen-tuple contract enforced via
Object.freeze, the TS twin of the Python @dataclass(frozen=True)).
Properties
Section titled “Properties”eventDate
Section titled “eventDate”
readonlyeventDate:string
Calendar date the call airs / the market settles for (YYYY-MM-DD).
resolutionRule
Section titled “resolutionRule”
readonlyresolutionRule:string
Stable settlement-rule label (not an executable rule). Kalshi resolutions carry RESOLUTION_RULE; Polymarket derives carry the any-speaker variant.
resolutionStatus
Section titled “resolutionStatus”
readonlyresolutionStatus:"qualifying_event"|"no_qualifying_event"
Whether a qualifying call exists for this date. "qualifying_event" for a
normal resolution; "no_qualifying_event" when a derive sees a
postponed/cancelled call. The Kalshi resolveEarnings path is always
"qualifying_event".
targetWord
Section titled “targetWord”
readonlytargetWord:string
ticker
Section titled “ticker”
readonlyticker:string
EarningsRow
Section titled “EarningsRow”A canonical earnings row emitted by parseEarningsPayload. Carries the passthrough schema fields present on the source row plus the SDK overlay.
Properties
Section titled “Properties”callId?
Section titled “callId?”
readonlyoptionalcallId:string
delivery
Section titled “delivery”
readonlydelivery:"hosted"|"live"
Delivery channel lineage: "live" or "hosted".
eventTime
Section titled “eventTime”
readonlyeventTime:null|string
Call air time (ISO-8601 UTC), or null if absent.
kalshiCounted?
Section titled “kalshiCounted?”
readonlyoptionalkalshiCounted:boolean
knowledgeTime
Section titled “knowledgeTime”
readonlyknowledgeTime:string
Transcript availability (POST-call), ISO-8601 UTC. The PIT invariant knowledgeTime = transcript availability, NEVER the call air time — a model deciding before this instant must not see the mention.
matchedSurfaceForm?
Section titled “matchedSurfaceForm?”
readonlyoptionalmatchedSurfaceForm:string
mentionCount?
Section titled “mentionCount?”
readonlyoptionalmentionCount:number
offsetSeconds?
Section titled “offsetSeconds?”
readonlyoptionaloffsetSeconds:number
retrievedAt
Section titled “retrievedAt”
readonlyretrievedAt:string
When the SDK retrieved the row (ISO-8601 UTC).
roleSource?
Section titled “roleSource?”
readonlyoptionalroleSource:string
segment?
Section titled “segment?”
readonlyoptionalsegment:string
segmentIndex?
Section titled “segmentIndex?”
readonlyoptionalsegmentIndex:number
source
Section titled “source”
readonlysource:"earnings_call"
Shared source identity — always EARNINGS_SOURCE_IDENTITY.
speakerName?
Section titled “speakerName?”
readonlyoptionalspeakerName:string
speakerRole?
Section titled “speakerRole?”
readonlyoptionalspeakerRole:string
termCanonical?
Section titled “termCanonical?”
readonlyoptionaltermCanonical:string
readonlyoptionaltext:string
ticker?
Section titled “ticker?”
readonlyoptionalticker:string
EarningsStreamRow
Section titled “EarningsStreamRow”A canonical LIVE streaming row yielded by consumeEarningsStream.
Mirrors the Python _project_stream_row output. Carries the schema
delta fields (isFinal / spokenAt / streamSeq / resolutionStatus) plus
the SDK overlay (source / knowledgeTime). kalshiCounted is passed
through verbatim — the consumer never re-derives it.
Properties
Section titled “Properties”callId?
Section titled “callId?”
readonlyoptionalcallId:string
readonlyevent:"transcript_segment"|"fact_delta"|"end_of_call"|"resume_incomplete"
The SSE event that produced this row.
isFinal?
Section titled “isFinal?”
readonlyoptionalisFinal:boolean
STT-segment finality ONLY — never settlement authority (P2).
kalshiCounted?
Section titled “kalshiCounted?”
readonlyoptionalkalshiCounted:boolean
Passed through from the fact-delta row — NEVER re-derived client-side.
knowledgeTime
Section titled “knowledgeTime”
readonlyknowledgeTime:null|string
STT-finalization/publish wallclock (ISO-8601 UTC, >= spokenAt), or null.
matchedSurfaceForm?
Section titled “matchedSurfaceForm?”
readonlyoptionalmatchedSurfaceForm:string
mentionCount?
Section titled “mentionCount?”
readonlyoptionalmentionCount:number
offsetSeconds?
Section titled “offsetSeconds?”
readonlyoptionaloffsetSeconds:number
resolutionStatus?
Section titled “resolutionStatus?”
readonlyoptionalresolutionStatus:string
Provisional for a counted fact delta; a live count is never settled.
roleSource?
Section titled “roleSource?”
readonlyoptionalroleSource:string
segment?
Section titled “segment?”
readonlyoptionalsegment:string
segmentIndex?
Section titled “segmentIndex?”
readonlyoptionalsegmentIndex:number
source
Section titled “source”
readonlysource:"earnings.hosted.stream"
Always EARNINGS_LIVE_STREAM_SOURCE — provisional live lineage.
speakerName?
Section titled “speakerName?”
readonlyoptionalspeakerName:string
speakerRole?
Section titled “speakerRole?”
readonlyoptionalspeakerRole:string
spokenAt
Section titled “spokenAt”
readonlyspokenAt:null|string
Aired event time (ISO-8601 UTC), or null.
streamSeq
Section titled “streamSeq”
readonlystreamSeq:null|number
Monotonic SSE id: = stream_seq (drives Last-Event-ID resume).
termCanonical?
Section titled “termCanonical?”
readonlyoptionaltermCanonical:string
readonlyoptionaltext:string
ticker?
Section titled “ticker?”
readonlyoptionalticker:string
EventSourceLike
Section titled “EventSourceLike”The minimal EventSource surface the consumer needs — declared structurally
so tests can inject a mock without a DOM. Matches the browser EventSource.
Properties
Section titled “Properties”onerror
Section titled “onerror”onerror:
null| (event) =>void
Methods
Section titled “Methods”addEventListener()
Section titled “addEventListener()”addEventListener(
type,listener):void
Parameters
Section titled “Parameters”string
listener
Section titled “listener”(event) => void
Returns
Section titled “Returns”void
close()
Section titled “close()”close():
void
Returns
Section titled “Returns”void
FetchEarningsHostedOptions
Section titled “FetchEarningsHostedOptions”Extends
Section titled “Extends”FetchWithRetryOptions
Properties
Section titled “Properties”hostedUrl
Section titled “hostedUrl”
readonlyhostedUrl:string
The hosted feed base URL. REQUIRED — the SDK ships no default endpoint (the serving layer is the satellite +).
retrievedAt?
Section titled “retrievedAt?”
readonlyoptionalretrievedAt:string
Retrieval timestamp override (ISO-8601 UTC). Default: now.
HostedStreamOptions
Section titled “HostedStreamOptions”Properties
Section titled “Properties”apiKey
Section titled “apiKey”
readonlyapiKey:string
The MOSTLYRIGHT_API_KEY. REQUIRED. Used to MINT a signed, single-scope
?token= locally (the browser cannot set an x-api-key header);
the raw key is never placed in the URL.
callId
Section titled “callId”
readonlycallId:string
Call id filter for the stream.
eventSourceFactory?
Section titled “eventSourceFactory?”
readonlyoptionaleventSourceFactory:EventSourceFactory
Opens an EventSource for a URL. Default: new EventSource(url) (browser).
Injectable so non-browser tests can mock it.
hostedUrl
Section titled “hostedUrl”
readonlyhostedUrl:string
The earnings serving base URL (MOSTLYRIGHT_FINANCE_HOSTED_URL) — the deployed
mr-serving origin. REQUIRED; a missing seam throws HostedConfigError.
maxReconnects?
Section titled “maxReconnects?”
readonlyoptionalmaxReconnects:number
Max reconnect attempts after a terminal disconnect before giving up.
Default 5. Each attempt re-opens with the last seen Last-Event-ID.
signal?
Section titled “signal?”
readonlyoptionalsignal:AbortSignal
Optional AbortSignal — when fired, the stream closes the EventSource and
ends iteration cleanly (no further reconnect).
ticker
Section titled “ticker”
readonlyticker:string
Ticker filter for the stream.
MessageEventLike
Section titled “MessageEventLike”The minimal MessageEvent surface: a JSON data string + lastEventId.
Properties
Section titled “Properties”
readonlydata:string
lastEventId?
Section titled “lastEventId?”
readonlyoptionallastEventId:string
ParseEarningsPayloadOptions
Section titled “ParseEarningsPayloadOptions”Properties
Section titled “Properties”retrievedAt?
Section titled “retrievedAt?”
readonlyoptionalretrievedAt:string
Retrieval timestamp (ISO-8601 UTC). Default: now.
source?
Section titled “source?”
readonlyoptionalsource:"earnings.live"|"earnings.hosted"
Delivery channel source id. Only earnings.hosted is browser-viable here;
earnings.live throws (server-only). Default earnings.hosted.
PolymarketEarningsEvent
Section titled “PolymarketEarningsEvent”Untrusted Polymarket event payload shape (all fields optional).
Properties
Section titled “Properties”eventDate?
Section titled “eventDate?”
readonlyoptionaleventDate:string
ISO YYYY-MM-DD calendar date. A time-bearing value is rejected.
readonlyoptionalname:string
readonlyoptionalslug:string
status?
Section titled “status?”
readonlyoptionalstatus:string
targetWord?
Section titled “targetWord?”
readonlyoptionaltargetWord:string
ticker?
Section titled “ticker?”
readonlyoptionalticker:string
title?
Section titled “title?”
readonlyoptionaltitle:string
webcastUrl?
Section titled “webcastUrl?”
readonlyoptionalwebcastUrl:string
ResolveEarningsOptions
Section titled “ResolveEarningsOptions”Properties
Section titled “Properties”targetWord
Section titled “targetWord”
readonlytargetWord:string
The word/phrase the market resolves on. Required, non-empty.
Type Aliases
Section titled “Type Aliases”EarningsStreamEvent
Section titled “EarningsStreamEvent”EarningsStreamEvent: typeof
SSE_STREAM_EVENTS[number]
EventSourceFactory()
Section titled “EventSourceFactory()”EventSourceFactory: (
url) =>EventSourceLike
Factory that opens an EventSource for a fully-formed URL (with ?token=).
In the browser this is (url) => new EventSource(url); tests inject a mock.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Variables
Section titled “Variables”EARNINGS_CALENDAR_SEED
Section titled “EARNINGS_CALENDAR_SEED”
constEARNINGS_CALENDAR_SEED:ReadonlyArray<EarningsCalendarRow>
EARNINGS_SERIES_ROSTER
Section titled “EARNINGS_SERIES_ROSTER”
constEARNINGS_SERIES_ROSTER:ReadonlySet<string>
TICKER_HQ_TIMEZONE
Section titled “TICKER_HQ_TIMEZONE”
constTICKER_HQ_TIMEZONE:Readonly<Record<string,string>>
transcripts
Section titled “transcripts”
consttranscripts:object
The finance earnings-transcripts namespace — the curated verb surface.
get— fetch hosted transcript rows (browser/MV3-viable hosted consumer).stream— consume the hosted SSE transcript stream (Last-Event-ID reconnect).resolve— the Kalshi earnings-mention resolver.derive— a Polymarket earnings event → resolution.
Type declaration
Section titled “Type declaration”derive()
Section titled “derive()”
readonlyderive: (event) =>null|EarningsResolution=deriveEarnings
Derive a frozen EarningsResolution from a Polymarket event payload.
The payload is untrusted. The derive refuses (returns null) when:
- the slug/title/name does not look like an earnings-mention market;
- a
webcastUrlis present but its host is NOT on WEBCAST_HOST_ALLOWLIST (security boundary — refuse before derive); - the
tickeris missing or not in EARNINGS_SERIES_ROSTER; targetWordoreventDateis missing / unparseable.
A postponed / cancelled call yields a resolution with
resolutionStatus="no_qualifying_event".
Parameters
Section titled “Parameters”Returns
Section titled “Returns”null | EarningsResolution
readonlyget: (ticker,eventDate,options) =>Promise<DataResult<EarningsRow>> =fetchEarningsHosted
Fetch + parse the hosted earnings feed for a ticker on an event date.
Mirrors awc.ts graceful-degradation discipline: returns [] on 4xx,
timeout, exhausted retries, or a non-JSON/malformed body — NEVER throws for
a transport/parse failure (a caller AbortSignal still propagates). Rows are
byte-equivalent to the Python EarningsAdapter.from_rows(source="earnings.hosted")
output; only the delivery lineage differs between live and hosted.
Browser-viable: fetch + JSON only. For endpoints without CORS headers, run
behind a Chrome MV3 service worker (host_permissions) or a CORS proxy — same
posture as fetchAwcMetars.
Parameters
Section titled “Parameters”ticker
Section titled “ticker”string
eventDate
Section titled “eventDate”string
options
Section titled “options”Returns
Section titled “Returns”Promise<DataResult<EarningsRow>>
resolve()
Section titled “resolve()”
readonlyresolve: (contractId,eventDate,options) =>EarningsResolution=resolveEarnings
Resolve a Kalshi earnings-mention contract to its frozen tuple.
The contractId is the Kalshi market identifier — one of the three root
variants KXEARNINGSMENTION<TICKER> (e.g. KXEARNINGSMENTIONNKE),
KXMENTIONEARN<TICKER>, or the Berkshire fixed root KXBRKEM. The suffix
is the ticker; it is validated against EARNINGS_SERIES_ROSTER.
Parameters
Section titled “Parameters”contractId
Section titled “contractId”string
Kalshi market identifier. Case-insensitive.
eventDate
Section titled “eventDate”The calendar date the call airs / the market settles for.
Either a UTC date-only Date (H/M/S/ms == 0) or a YYYY-MM-DD string.
string | Date
options
Section titled “options”Returns
Section titled “Returns”A frozen EarningsResolution.
Throws
Section titled “Throws”The contract id matches no known root, the ticker is unknown, the event date is time-bearing/invalid, or the target word is empty.
stream()
Section titled “stream()”
readonlystream: (options) =>AsyncGenerator<EarningsStreamRow,void,void> =hostedStream
Consume the earnings live /stream SSE feed with Last-Event-ID reconnect.
Opens new EventSource("${MOSTLYRIGHT_FINANCE_HOSTED_URL}/stream?...&apiKey=…"),
subscribes to the named events, yields projected rows tagged
source="earnings.hosted.stream", and tracks the last seen event id. On a
terminal disconnect (the 3600s Cloud Run cut, an instance swap) it RE-OPENS a
fresh EventSource carrying the last seen id as lastEventId= so the
server replays the buffered tail — ZERO events lost across the cut. Iteration
ends on end_of_call, on signal abort, or after maxReconnects failed
reconnects.
Browser/MV3-viable: EventSource + JSON only. No Node built-ins.
Parameters
Section titled “Parameters”options
Section titled “options”Returns
Section titled “Returns”AsyncGenerator<EarningsStreamRow, void, void>
Throws
Section titled “Throws”when MOSTLYRIGHT_FINANCE_HOSTED_URL / apiKey is missing —
surfaced BEFORE the first connection.
Throws
Section titled “Throws”when reconnection is exhausted (maxReconnects reached) — the last
transport error is re-thrown so the caller sees the failure, not a silent
gap.
version
Section titled “version”
constversion:"1.9.9"="1.9.9"
Public package version; kept in lockstep with package.json.
WEBCAST_HOST_ALLOWLIST
Section titled “WEBCAST_HOST_ALLOWLIST”
constWEBCAST_HOST_ALLOWLIST:ReadonlySet<string>
Netloc allowlist for webcast / resolution-source hosts. A host NOT on this
list is refused before any provider classification or derive (
security boundary) — mirrors polymarket.RESOLUTION_SOURCE_ALLOWLIST. These
are the exact public webcast hosts behind the provider fingerprints; a
substring fingerprint alone is NOT a trust decision — the allowlist is.
WEBCAST_PROVIDER_FINGERPRINTS
Section titled “WEBCAST_PROVIDER_FINGERPRINTS”
constWEBCAST_PROVIDER_FINGERPRINTS:Readonly<Record<string,string>>
Functions
Section titled “Functions”alignEventDate()
Section titled “alignEventDate()”alignEventDate(
eventDate,ticker,options):string
Coerce + hq-tz-correct an earnings eventDate to the issuer-local date.
Parameters
Section titled “Parameters”eventDate
Section titled “eventDate”The calendar date the call airs / the market settles for.
Either a UTC date-only Date (H/M/S/ms == 0) or a YYYY-MM-DD string —
a time-bearing Date is rejected.
string | Date
ticker
Section titled “ticker”string
The issuer ticker; its IANA HQ timezone is looked up in TICKER_HQ_TIMEZONE.
options
Section titled “options”Returns
Section titled “Returns”string
The HQ-local calendar date as YYYY-MM-DD.
Throws
Section titled “Throws”eventDate is time-bearing/invalid, ticker is
unknown, callInstant is naive (no UTC offset), or the re-projected date
diverges from eventDate by more than ±1 calendar day.