Class: Context

bemap.Context()

Base class for Context.

Constructor

new Context()

Parameters:
Name Type Description
options. object
Source:

Members

(static) TILES_AUTH_DEFAULTS

Default tile-auth wire config: `mode:'auto'` — resolve per deployment at runtime (same registrable domain as `tilesHost` ⇒ `cookie`, else ⇒ `header`), so a new consumer needs NO auth config and never silently breaks cross-site (where a third-party cookie is blocked in incognito/Safari/Firefox). Consumer-supplied fields are merged over these.
Since:
  • 2.0.0
Source:

bemapEnv :string|null

OPTIONAL — environment selector for a multi-environment proxy, sent as the `X-BeMap-Env` header. Only a non-empty trimmed string is sent; anything else omits the header entirely (a single-environment proxy needs none).
Type:
  • string | null
Since:
  • 2.0.2
Source:

chargingStationProvider :string

Default charging-station provider name (e.g. `'ecoMovement'`). When set, `bemap.ChargingStations.search()` and `bemap.EvSmartRouting.calculate()` fall back to this value when the request itself does not specify one. Only names exposed by the user's ACL (see `bemap.helpers.listChargingStationProviders`) are accepted server-side.
Type:
  • string
Since:
  • 1.5.0
Source:

glyphsUrl :string|null

Optional override for the MapLibre glyphs (font) URL template, e.g. `'https://my-host/fonts/{fontstack}/{range}.pbf'`. When set it wins over every style's own `glyphs`. Leave unset and the library bundles no fonts: the tiny fallback style requests none, and server styles fetch their own glyphs from the Worker (a root-relative `/fonts/...` is absolutised to `/fonts/...` by `bemap.TilesStyle.resolvePlaceholders`).
Type:
  • string | null
Since:
  • 2.0.0
Source:

(protected) host :string

Define the host name of BeMap server. By default "bemap.benomad.com" (production; the same service also answers at "bemap-prod.benomad.com").
Type:
  • string
Source:

(protected) login :string

Define the login.
Type:
  • string
Source:

(protected) password :string

Define the Password.
Type:
  • string
Source:

(protected) path :string

Define the path of bgis context. The string must be start with / character. By default "/bgis/".
Type:
  • string
Source:

(protected) protocol :string

Define the protocol used. The HTTP or HTTPS, by default the HTTP.
Type:
  • string
Source:

proxy :string|null

OPTIONAL — put your own proxy in front of BeMap so credentials never reach the browser (EVMOVE-307). Written like `host`: a bare host is enough and the `https://` prefix is **optional**, with a path prefix if your proxy lives under one — `'my-proxy.example.com'`, `'my-proxy.example.com/bemap'`, `'https://my-proxy.example.com'`, `'localhost:8787'`. When no scheme is written, the protocol comes from `secure` exactly as it does for `host`. Normalised once here (canonical `origin[+path]`, trailing slash stripped) and stored back, so every consumer reads the same form. When set: REST/WMS URLs (`getBaseUrl()`) and the tiles login (`getTilesLoginUrl()`) go through the proxy, no BeMap credentials are sent (`getAuthUrlParams()` → `''`, no `Authorization`) — even if `login`/ `password` are also configured. Tile BYTES still go direct to `tilesHost` (a public host), so tile auth uses the token header wire. A query/fragment or embedded credentials are dropped with a one-shot console warning; only a value with no usable host left (a non-`http(s)` scheme, or a string that is not a host at all) throws — silently turning proxy mode OFF would fall back to direct requests, i.e. leak the very credentials this option exists to hide.
Type:
  • string | null
Since:
  • 2.0.2
Source:

tilesAuth :Object|String|null

Tile-auth wire configuration — HOW authenticated requests to `tilesHost` carry their auth. A grouped object `{ mode, credentials, tokenHeader, tokenParam }` (or the shorthand string `'cookie'|'header'|'query'`), normalised by `bemap.Context._resolveTilesAuth`. Unset ⇒ `mode:'auto'` — resolved per deployment (same site as `tilesHost` ⇒ cookie, cross-site ⇒ header), so a consumer needs no auth config and never silently breaks cross-site. Read via `getTilesAuth()`; `bemap.MapLibreMap` lets a per-map `tilesAuth` opt override it field-by-field.
Type:
  • Object | String | null
Since:
  • 2.0.0
Source:

tilesFallbackToDefault :boolean

What to do when `geoserver` was inherited as the PMTiles map name but the Worker's `/api/maps` catalog has no such map — a BGIS-only provider (`herehlp`, `addok`, `photon`, `nominatim`, `tomtom`) has no vector map. `false` (the default) leaves the basemap empty, so a map never silently shows a DIFFERENT provider's data than the one that was selected. `true` loads the Worker's server-default map instead (the earlier behaviour). An explicit `tilesFile` pin is unaffected either way — it keeps surfacing its own 403/404, since a misspelled or unauthorised tileset is a configuration error, not a provider without tiles.
Type:
  • boolean
Since:
  • 2.0.4
Source:

tilesFile :string

PMTiles map served by the Worker — a bare name (the `.pmtiles` suffix is optional): an alias (`'osm'`, `'here'`) or an exact tileset (`'OSM_250901_WORLD'`). Defaults to `'default'`, which the Worker resolves to the configured default map server-side (via `_config/maps.json`), so the client never pins a map version. Aliases are case-insensitive.
Type:
  • string
Since:
  • 2.0.0
Source:

tilesHost :string|null

BeNomad Tiles Worker host, e.g. `'mptiles-api.benomad.net'`. When set, `bemap.MapLibreMap` will route its background through PMTiles instead of WMS. Leaflet and OpenLayers ignore this field and keep WMS unchanged.
Type:
  • string | null
Since:
  • 2.0.0
Source:

tilesPath :string

Optional URL path prefix on `tilesHost`. Empty by default.
Type:
  • string
Since:
  • 2.0.0
Source:

tilesProtocol :string

Protocol used to reach `tilesHost`. Default `'https:'`.
Type:
  • string
Since:
  • 2.0.0
Source:

tilesVersions :Object.<string, string>

BeNomad-Tiles archive version tokens, keyed by resolved map name (EVMOVE-457). Populated at runtime from the Worker's `/api/maps` (`aliasVersions`/`versions`). When a token is present, `getTilesFileUrl()` appends `?v=` so a rebuilt-under-the-same-name archive becomes a new URL and the browser fetches fresh bytes instead of stale cached slices. Empty by default → URLs are byte-identical to earlier releases.
Type:
  • Object.<string, string>
Since:
  • 2.0.1
Source:

tokenStorage :string

Where the JWT lives between page loads: `'session'` (default), `'local'`, or `'memory'` (no persistence).
Type:
  • string
Since:
  • 2.0.0
Source:

Methods

(static) _normalizeProxy(rawopt, defaultProtocolopt) → {String|null}

Normalise + validate a `proxy` option (EVMOVE-307) into the canonical `origin[+path]` form, with any trailing slash stripped — so composing it with `this.path` (which starts with `/`) can never produce `//`. **The scheme is optional.** `proxy` is written like `host`: a bare host is enough and inherits its protocol from `secure`, so `{ secure: true, proxy: 'my-proxy.example.com' }` and `{ proxy: 'https://my-proxy.example.com' }` are the same thing. Accepted: `my-proxy.example.com`, `my-proxy.example.com/prefix`, `localhost:8787`, `//my-proxy.example.com`, and every `http(s)://…` form (unchanged). Forgiving where a human's intent is unambiguous: a `?query`/`#fragment` or embedded `user:pass@` credentials are dropped with a one-shot console notice rather than refusing to boot. It still THROWS when nothing usable is left (a non-`http(s)` scheme, or a string that is not a host) — silently turning proxy mode off is the dangerous outcome, because the SDK would then fall back to direct requests and send the very credentials `proxy` exists to hide. A falsy input returns `null` (proxy mode off, no throw).
Parameters:
Name Type Attributes Description
raw String <optional>
defaultProtocol String <optional>
 `'https:'` (default) or `'http:'` — the Context passes its own `protocol` (i.e. `secure`) here.
Since:
  • 2.0.2
Source:
Returns:
Type
String | null

(static) _resolveAutoMode(cfg, tilesHost, appHostopt) → {Object}

Resolve a `mode:'auto'` config to a concrete `cookie` (same-site) or `header` (cross-site) mode for the current page. A no-op for any explicit mode. Header is the safe fallback — it works in every browser and deployment — so we only pick `cookie` on a confident same-site match, never breaking cross-site. This is the ONE place `'auto'` is turned into a wire mode, called by the fetch interceptor / `TilesStyle.fetch`. `appHost` defaults to the current `window.location.hostname` (pass it explicitly in tests / non-browser hosts).
Parameters:
Name Type Attributes Description
cfg Object resolved config from `_resolveTilesAuth` (may be `mode:'auto'`)
tilesHost String
appHost String <optional>
Since:
  • 2.0.0
Source:
Returns:
`cfg` unchanged, or a clone with a concrete `mode`
Type
Object

(static) _resolveTilesAuth(rawopt, baseopt) → {Object}

Normalise a `tilesAuth` value into a fully-defaulted `{ mode, credentials, tokenHeader, tokenParam }`. Mirrors `bemap.Map._resolveControlOptions`: accepts `undefined` (→ defaults), a string shorthand (`'auto'|'cookie'|'header'|'query'` → that mode + defaults), or a partial object (missing fields filled). An unrecognised `mode` falls back to `'auto'`. `raw` fields win over `base` fields win over the defaults — so a per-map opt (`raw`) can override a Context config (`base`) field-by-field. NOTE: this is a PURE normaliser — it may return `mode:'auto'`. The runtime apply sites resolve `'auto'` → `cookie`/`header` via `_resolveAutoMode`.
Parameters:
Name Type Attributes Description
raw Object | String <optional>
base Object | String <optional>
Since:
  • 2.0.0
Source:
Returns:
Type
Object

(static) _sameSite(appHost, tilesHost) → {Boolean}

`true` when `appHost` and `tilesHost` share the same registrable domain — i.e. the browser treats the tile request as first-party, so the `SameSite=None` session cookie is sent (works in incognito/Safari/Firefox). Different domains ⇒ third-party cookie ⇒ blocked ⇒ the caller must carry the token itself.
Parameters:
Name Type Description
appHost String e.g. `window.location.hostname`
tilesHost String e.g. `ctx.tilesHost`
Since:
  • 2.0.0
Source:
Returns:
Type
Boolean

getAuthUrlParams() → {String}

URL auth parameters (`appid=…&appcode=…`) for REST/WMS URLs. Returns `''` when there are no credentials, and **always `''` in proxy mode** (`ctx.proxy`, EVMOVE-307) — credentials never travel to a proxy, even when `login`/`password` are also configured. (Before 2.0.2 the credential-less case returned `null`, which string-concatenated into URLs as a literal `"null"`.)
Source:
Returns:
`appid=…&appcode=…`, or `''`
Type
String

getBaseUrl() → {String}

Base URL of the BeMap REST/WMS endpoints — `protocol://host + path`. In **proxy mode** (`ctx.proxy`, EVMOVE-307) the consumer's own proxy origin replaces `protocol://host`, i.e. ` + path`, so every REST/WMS call is routed through it (the proxy adds the credentials server-side).
Source:
Returns:
BeMap URL
Type
String

getBemapEnv() → {String|null}

The environment selector sent as `X-BeMap-Env` on proxy requests, or `null`.
Since:
  • 2.0.2
Source:
Returns:
Type
String | null

getChargingStationProvider() → {String|null}

Return the configured default charging-station provider, or `null` when none is set. Mirrors the convenience shape of `getGeoserver()`.
Since:
  • 1.5.0
Source:
Returns:
Type
String | null

getGeoserver() → {String}

Return the default BaMap Geoserver of context.
Source:
Returns:
BeMap Geoserver
Type
String

getProxy() → {String|null}

The effective, NORMALISED proxy for this Context (EVMOVE-307), or `null` when proxy mode is off. Normalises **on read** and re-checks whenever the stored `proxy` value has changed since the last call: `bemap.RuntimeConfig`'s Proxy `set` trap writes unknown keys straight onto the shared Context, so a runtime `ctx.proxy = '…'` never passes through the constructor. Reading through this getter means such a write is still validated (it throws on a bad URL) and the `getBaseUrl()` memo is invalidated instead of serving the old origin.
Since:
  • 2.0.2
Source:
Returns:
Type
String | null

getProxyHeaders() → {Object}

Extra HTTP headers required by the configured proxy (EVMOVE-307), as a plain object for `fetch`-based call sites. Currently `X-BeMap-Env` when `bemapEnv` is a non-empty string; `{}` otherwise (no proxy, or no env selector). Returns a FRESH object on every call — callers merge/mutate it.
Since:
  • 2.0.2
Source:
Returns:
Type
Object

getProxyHeadersList() → {Array.<{key: String, value: String}>}

Same header set as bemap.Context#getProxyHeaders, in the `[{key, value}]` shape `bemap.ajax` (and `evmove5`'s dao) consumes. Derived from `getProxyHeaders()`, so a future header appears in both automatically. Returns a FRESH array on every call — `bemap.ajax` PUSHES onto the array it is given (Content-Type), so a shared array would grow without bound.
Since:
  • 2.0.2
Source:
Returns:
Type
Array.<{key: String, value: String}>

getTilesAuth() → {Object}

Resolved tile-auth wire config `{ mode, credentials, tokenHeader, tokenParam }` — fully defaulted; `mode` is `'auto'` when unset (the fetch interceptor and `TilesStyle.fetch` resolve `'auto'` → `cookie`/`header` per deployment via `bemap.Context._resolveAutoMode`). See `this.tilesAuth`.
Since:
  • 2.0.0
Source:
Returns:
Type
Object

getTilesBaseUrl() → {string|null}

Return the base URL of the BeNomad Tiles Worker, e.g. `'https://mptiles-api.benomad.net'`.
Since:
  • 2.0.0
Source:
Returns:
Type
string | null

getTilesDefaultStyleUrl() → {string|null}

URL of the Worker default-STYLE pointer (`/api/default-style`) — returns the name of the MapLibre style applied when the developer pins no style. Used for the "load the live charte from the server after login" default path.
Since:
  • 2.0.0
Source:
Returns:
Type
string | null

getTilesDefaultUrl() → {string|null}

URL of the Worker default-map endpoint (`/api/default`) — returns the filename the `default` alias currently resolves to (or `null` server-side).
Since:
  • 2.0.0
Source:
Returns:
Type
string | null

getTilesFileUrl(fileopt) → {string|null}

Build the URL of a PMTiles archive (or `{z}/{x}/{y}.pbf` directory) served by the Worker. Resolves to `https://{tilesHost}{tilesPath}/{file}`.
Parameters:
Name Type Attributes Description
file string <optional>
 Archive file name; defaults to `Context.tilesFile`.
Since:
  • 2.0.0
Source:
Returns:
Type
string | null

getTilesLoginUrl() → {string|null}

URL of the tiles login endpoint. Normally the Worker's `/api/login` on `tilesHost`; in **proxy mode** (`ctx.proxy`, EVMOVE-307) it is `/tiles/login` instead, because the login is the one tiles call that needs BeMap credentials and the proxy injects them server-side.
Since:
  • 2.0.0
Source:
Returns:
Type
string | null

getTilesLogoutUrl() → {string|null}

URL of the Worker logout endpoint (`/api/logout`).
Since:
  • 2.0.0
Source:
Returns:
Type
string | null

getTilesMapsUrl() → {string|null}

URL of the Worker map-config discovery endpoint (`/api/maps`) — returns the default map, aliases, and the allow-listed tileset filenames for this env.
Since:
  • 2.0.0
Source:
Returns:
Type
string | null

getTilesStatusUrl() → {string|null}

URL of the Worker status endpoint (`/api/status`).
Since:
  • 2.0.0
Source:
Returns:
Type
string | null

getTilesStylesUrl() → {string|null}

URL of the Worker style-list endpoint (`/api/styles`) — returns the allow-listed style files for this env.
Since:
  • 2.0.0
Source:
Returns:
Type
string | null

getTilesStyleUrl(name) → {string|null}

URL of a named MapLibre style JSON served by the Worker. Accepts either a bare style name (`'openfreemap_graylevel'` → `/styles/openfreemap_graylevel`) or a Worker-relative path as returned by `/api/styles` (`'styles/openfreemap_graylevel.json'` → `/styles/openfreemap_graylevel.json`). A leading slash is stripped; a value that already carries a path segment is resolved against the tilesHost root rather than re-nested under `/styles/`. Returns `null` when there is no tilesHost or no name.
Parameters:
Name Type Description
name String
Since:
  • 2.0.0
Source:
Returns:
Type
string | null

getTilesVersion(nameopt) → {String|null}

Version token currently known for a BeNomad-Tiles map (EVMOVE-457), or null.
Parameters:
Name Type Attributes Description
name String <optional>
 Resolved map name; defaults to `resolveTilesFile()`.
Since:
  • 2.0.1
Source:
Returns:
Type
String | null

hasTilesConfig() → {boolean}

Return `true` when this Context has a `tilesHost` configured, meaning `bemap.MapLibreMap` should route the background through BeNomad Tiles.
Since:
  • 2.0.0
Source:
Returns:
Type
boolean

isAuthInPost() → {boolean}

Return true if the authentication parameters will be write in the POST data of request.
Source:
Returns:
true if the authentication parameters will be write in the POST data of request..
Type
boolean

post(options)

Perform a HTTP Post request.
Parameters:
Name Type Description
options Object
Source:

resolveTilesFile(explicitopt) → {String}

Decide which tiles map (PMTiles alias / tileset) MapLibre should load. Precedence, highest first: 1. an explicit per-call tile parameter (`explicit`, e.g. `opts.tilesFile`) 2. an explicit `ctx.tilesFile` (any value other than the 'default' sentinel) 3. `ctx.geoserver`, when set — so `geoserver: 'osm'` loads the 'osm' tiles 4. the literal 'default' — the Worker resolves it server-side The string `'default'` is treated as "not explicitly chosen", so a configured `geoserver` outranks the implicit default that `ctx.tilesFile` carries when the caller never set a tiles map.
Parameters:
Name Type Attributes Description
explicit String <optional>
 A per-call tilesFile that outranks the ctx values.
Since:
  • 2.0.0
Source:
Returns:
Type
String

setAuthInPost()

Set to true if the authentication parameters will be write in the POST data of request.
Source:

setProxy(raw) → {bemap.Context}

Set (or clear with `null`) the proxy at runtime, validating + normalising it and invalidating the base-URL memo. Accepts the same shapes as the constructor option, including a bare host (the protocol follows `secure`). **Set `proxy` BEFORE constructing a map.** This exists for config layers that mutate a live Context, and everything URL-shaped follows immediately (`getBaseUrl()`, `getAuthUrlParams()`, `getTilesLoginUrl()`, all v1/v2 service calls, and — for a map that already had a proxy — MapLibre's per-request env header). What it CANNOT retrofit: - a `bemap.MapLibreMap` built on a proxy-less Context has no proxy `transformRequest` wrapper installed at all, so it will never send `X-BeMap-Env` (its tile auth is untouched, and services still switch); - **no URL already built into a live map is rewritten** — a MapLibre WMS/raster source added to the style, and any Leaflet/OpenLayers layer, keep the URL they were created with, so their requests keep going to the OLD proxy (only the env header follows the new one). Rebuild the source/layer — or re-apply the style — to move that traffic; - a tiles JWT already minted for the previous proxy stays in use until it expires or `TilesAuth.logout()` clears it.
Parameters:
Name Type Description
raw String | null
Since:
  • 2.0.2
Source:
Returns:
this
Type
bemap.Context

setTilesVersion(name, tokenopt) → {bemap.Context}

Record (or clear) the version token for a BeNomad-Tiles map (EVMOVE-457). A non-empty string sets it; anything else clears it. Keyed by resolved map name, so several maps sharing one Context can each carry their own version.
Parameters:
Name Type Attributes Description
name String Resolved map name.
token String <optional>
 Opaque version token from `/api/maps`.
Since:
  • 2.0.1
Source:
Returns:
Type
bemap.Context