@mostlyrightmd/core/hosted
Classes
Section titled “Classes”HostedConfigError
Section titled “HostedConfigError”A misconfiguration of the opt-in hosted seams (MOSTLYRIGHT_WEATHER_HOSTED_URL /
MOSTLYRIGHT_FINANCE_HOSTED_URL / MOSTLYRIGHT_API_KEY) — raised before any network
call so the caller gets a clear, actionable error instead of a raw 401/null.
Mirrors the Python _hosted_client “clear config error” contract: a missing
seam is a caller/deployment bug, not a transport failure, so it is a distinct
typed error a caller can branch on.
Extends
Section titled “Extends”Constructors
Section titled “Constructors”new HostedConfigError()
Section titled “new HostedConfigError()”new HostedConfigError(
message,options):HostedConfigError
Parameters
Section titled “Parameters”message
Section titled “message”string
options
Section titled “options”Returns
Section titled “Returns”Overrides
Section titled “Overrides”Properties
Section titled “Properties”defaultErrorCode
Section titled “defaultErrorCode”
staticdefaultErrorCode:string="HOSTED_CONFIG"
Subclass override — the stable string enum surfaced via errorCode.
Overrides
Section titled “Overrides”MostlyrightError.defaultErrorCode
errorCode
Section titled “errorCode”
readonlyerrorCode:string
Inherited from
Section titled “Inherited from”requestId
Section titled “requestId”
readonlyrequestId:null|string
Inherited from
Section titled “Inherited from”source
Section titled “source”
readonlysource:null|string
Inherited from
Section titled “Inherited from”Methods
Section titled “Methods”toDict()
Section titled “toDict()”toDict():
Record<string,unknown>
Return a JSON-safe dict suitable for MCP error.data.
Returns
Section titled “Returns”Record<string, unknown>
Inherited from
Section titled “Inherited from”HostedResponseError
Section titled “HostedResponseError”A non-2xx (or otherwise failed) response from the hosted API — carries the HTTP status and the server message so the caller can branch (401 → bad key, 429 → global ceiling hit, 5xx → serving down).
Distinct from HostedConfigError, which fires before the request: this is a
transport failure after the request was issued. Mirrors the Python
hosted client’s “typed error with status + message” contract.
Extends
Section titled “Extends”Constructors
Section titled “Constructors”new HostedResponseError()
Section titled “new HostedResponseError()”new HostedResponseError(
message,options):HostedResponseError
Parameters
Section titled “Parameters”message
Section titled “message”string
options
Section titled “options”MostlyrightErrorOptions & object = {}
Returns
Section titled “Returns”Overrides
Section titled “Overrides”Properties
Section titled “Properties”defaultErrorCode
Section titled “defaultErrorCode”
staticdefaultErrorCode:string="HOSTED_RESPONSE"
Subclass override — the stable string enum surfaced via errorCode.
Overrides
Section titled “Overrides”MostlyrightError.defaultErrorCode
errorCode
Section titled “errorCode”
readonlyerrorCode:string
Inherited from
Section titled “Inherited from”requestId
Section titled “requestId”
readonlyrequestId:null|string
Inherited from
Section titled “Inherited from”source
Section titled “source”
readonlysource:null|string
Inherited from
Section titled “Inherited from”status
Section titled “status”
readonlystatus:null|number
The HTTP status code (e.g. 401, 429, 500), or null for a network error.
Methods
Section titled “Methods”toDict()
Section titled “toDict()”toDict():
Record<string,unknown>
Return a JSON-safe dict suitable for MCP error.data.
Returns
Section titled “Returns”Record<string, unknown>
Inherited from
Section titled “Inherited from”Interfaces
Section titled “Interfaces”HostedFetchOptions
Section titled “HostedFetchOptions”Properties
Section titled “Properties”apiKey
Section titled “apiKey”
readonlyapiKey:string
The MOSTLYRIGHT_API_KEY sent as the x-api-key header on every request.
In the MV3 extension this is read from chrome.storage at call time
(onboarding UX) — see docs/internal/hosted-api.md. Required: a missing key
throws HostedConfigError before any network call.
fetchImpl?
Section titled “fetchImpl?”
readonlyoptionalfetchImpl:FetchLike
Injectable fetch (default: the browser/MV3 global fetch). Tests pass a
mock; production leaves it undefined and uses the platform fetch.
signal?
Section titled “signal?”
readonlyoptionalsignal:AbortSignal
Optional AbortSignal for cancellation (propagated to the underlying
fetch). A caller-fired abort propagates as the abort rejection, not a
HostedResponseError — callers distinguish cancellation from a server 4xx.
HostedResponseLike
Section titled “HostedResponseLike”The minimal Response surface the shim reads. Matches the browser/MV3
Response (status + ok + .json()).
Properties
Section titled “Properties”
readonlyok:boolean
status
Section titled “status”
readonlystatus:number
Methods
Section titled “Methods”json()
Section titled “json()”json():
Promise<unknown>
Returns
Section titled “Returns”Promise<unknown>
text()
Section titled “text()”text():
Promise<string>
Returns
Section titled “Returns”Promise<string>
Type Aliases
Section titled “Type Aliases”FetchLike()
Section titled “FetchLike()”FetchLike: (
input,init?) =>Promise<HostedResponseLike>
The minimal fetch surface the shim needs — declared structurally so tests
can inject a mock without a global fetch (and so we never reach for a Node
HTTP client). Matches the browser/MV3 fetch.
Parameters
Section titled “Parameters”string
headers?
Section titled “headers?”Record<string, string>
method?
Section titled “method?”string
signal?
Section titled “signal?”AbortSignal
Returns
Section titled “Returns”Promise<HostedResponseLike>
Variables
Section titled “Variables”HOSTED_API_KEY_HEADER
Section titled “HOSTED_API_KEY_HEADER”
constHOSTED_API_KEY_HEADER:"x-api-key"
The auth header the hosted serving middleware reads. Matches the
server contract (curl -H "x-api-key: $MOSTLYRIGHT_API_KEY" ...).
Functions
Section titled “Functions”hostedFetchJson()
Section titled “hostedFetchJson()”hostedFetchJson(
url,options):Promise<unknown>
Issue a GET against the hosted API, adding the MOSTLYRIGHT_API_KEY header,
and parse the JSON body.
MV3-safe: uses only the browser/MV3 fetch + JSON — no node:*, no
http/https, no Buffer. The API key is sent as x-api-key on every
request; it is a public secret, and abuse is bounded server-side by the
global request ceiling, not by this shim.
Parameters
Section titled “Parameters”string
options
Section titled “options”Returns
Section titled “Returns”Promise<unknown>
Throws
Section titled “Throws”when apiKey is empty/missing, or when no
fetch is available and none was injected — raised before any request.
Throws
Section titled “Throws”when the response is non-2xx, or the body is not
valid JSON — carries the HTTP status + server message. A caller-fired
AbortSignal rejection is re-thrown as-is (not wrapped), so cancellation is
distinguishable from a server error.
joinHostedUrl()
Section titled “joinHostedUrl()”joinHostedUrl(
baseUrl,path):string
Join a base URL and a path, tolerating a trailing slash on the base and a
leading slash on the path (so MOSTLYRIGHT_WEATHER_HOSTED_URL="https://x/" + /satellite
yields https://x/satellite, never a double slash). Query strings pass
through unchanged on the path.
Parameters
Section titled “Parameters”baseUrl
Section titled “baseUrl”string
string
Returns
Section titled “Returns”string
requireHostedUrl()
Section titled “requireHostedUrl()”requireHostedUrl(
value,seamName):string
Require a configured hosted base URL seam — a small helper the per-endpoint
shims (satellite, hostedStream) share so the “missing MOSTLYRIGHT_WEATHER_HOSTED_URL /
MOSTLYRIGHT_FINANCE_HOSTED_URL” error is uniform and typed (HostedConfigError).
Parameters
Section titled “Parameters”undefined | null | string
seamName
Section titled “seamName”string
Returns
Section titled “Returns”string
Throws
Section titled “Throws”when value is empty/missing. seamName names
the env seam in the message (e.g. "MOSTLYRIGHT_WEATHER_HOSTED_URL").