Migrating to 4.0.1 (the current release) from v2

This page is the direct-to-current migration reference for Mapsted Maps JavaScript API customers currently on v2 (2.x, UMD-only, untyped). v3 was an intermediate release — v2 customers should skip it and migrate straight to the current release (4.0.1), which carries forward every v3 improvement and layers safety on top (typed events, structured errors, origin-validated postMessage).

Upgrading is optional. mapi.mapsted.com keeps serving v2.13.0, so your existing <script> integration continues to work with no action required — there is no forced upgrade. Migrate when you are ready to adopt the newer features below.

If you are currently on v3, see Migrating from v3 to 4.0.1 instead — a shorter doc that only covers the v3 → 4.0.1 deltas.

Every v2 method name still works in 4.0.1 via the backward-compatibility shim (src/migration/shim.ts). Each deprecated call logs one console.warn and then delegates to the current equivalent. The shim preserves your old method names, so you can migrate incrementally. It will be removed in a future major release — migrate before then.

1. Method renames

v2's public method names were renamed at the 4.0.1 boundary for clarity, casing consistency, and to align the event API with idiomatic JavaScript (on/off/once vs DOM-style listeners). One method (highlightStyle) was removed as dead code.

v2 method	4.0.1 method	Notes
initialize(options)	init(options)	Now returns Promise<MapInstance> — await it.
set(options)	init(options)	v2 set() was an alias for initialize().
changeFloorById(id)	navigateToFloorById(id)
changeFloorByName(name)	navigateToFloorByName(name)
setMapView(view)	setViewport(view)
centerOnMapoverlay(id)	centerOnMapOverlay(id)	Casing fix: Mapoverlay → MapOverlay.
setDefaultCustomRoutingConfig(cfg)	setDefaultRoutingConfig(cfg)
changeLanguage(code)	setLanguage(code)
addEventListener(event, fn)	on(event, fn)	on() returns an Unsubscribe function. Payloads are typed via discriminated overloads.
removeEventListener(event, fn)	off(event, fn)	Also adds once() for one-shot listeners.
highlightStyle()	(removed, no replacement)	v2 dead code — feature was never implemented. Always throws MAPSTED-1093 in 4.0.1.

Plus one public-constant removal:

• PRIVATE_CHILD_ACTION — was exposed in v2 and v3 by accident. 4.0.1 removes it from the public surface (CHL-27 security review). Remove the import; protocol handling is fully internal.

2. Event name normalization (WIRE_TO_PUBLIC_NAME)

v2 exposed two event names in the upstream wire-protocol casing (MAP_MOUNTED, IDLE_CHANGE). 4.0.1 normalizes these to camelCase public names. Normalization happens transparently inside the emitter, but handlers subscribed to the old wire names must rename:

v2 / wire-protocol name	4.0.1 public name
MAP_MOUNTED	mapMounted
IDLE_CHANGE	idleChange
(all other event names)	unchanged — already matched the current public names

The authoritative source is src/events.ts — the WIRE_TO_PUBLIC_NAME export. The full list of the 32 known events is in the Events reference.

3. SecurityConfig — postMessage origin validation (new in 4.0.1)

v2 accepted postMessage events from any origin. 4.0.1 introduces a public SecurityConfig contract so you can configure a multi-origin whitelist declaratively at init() time.

import {
  init,
  type SecurityConfig,
  DEFAULT_SECURITY_CONFIG,
  resolveConfig,
  validateOriginWithConfig,
} from '@mapsted/maps-js-api';

// Option 1 — supply security config at init() (recommended for most apps)
await init({
  mapsDomain: 'https://maps.mapsted.com',
  propertyId: 603,
  security: {
    allowedOrigins: ['https://maps.mapsted.com'],
    additionalOrigins: ['https://proxy.customer.com'],
    strictMode: true,
  },
});

// Option 2 — build your own validator (advanced consumers / custom integrations)
const cfg: SecurityConfig = resolveConfig({
  allowedOrigins: ['https://maps.mapsted.com'],
  strictMode: true,
});
window.addEventListener('message', (event) => {
  if (!validateOriginWithConfig(event, cfg)) return;
  // ... handle message ...
});

Key behaviour changes you need to be aware of:

• SecurityConfig.strictMode defaults to true. Origin mismatches throw MapstedError with code MAPSTED-1303 (ERR_SECURITY_CONFIG_ORIGIN_MISMATCH), not silent-discard. v2 consumers that relied on the forgiving default must either pass security.strictMode: false explicitly or whitelist the origins they actually need.
• allowedOrigins defaults to [] (deny-all). Callers must supply at least one origin. Forgetting to do so is caught at config-resolve time.
• additionalOrigins is a separate field for proxy setups, so you can extend the whitelist without reconstructing allowedOrigins.

Note on two strict modes. SecurityConfig.strictMode controls origin validation and is true by default. A separate migration shim strict mode (set via setStrictMode(true) or init({ strict: true })) controls deprecated-method behaviour and is false by default. The two are independent.

See the full contract in the TypeDoc reference.

4. Other breaking changes

• TypeScript + npm. 4.0.1 ships TypeScript types, .d.ts declarations, and an mapsted.maps npm package. v2 was CDN-only UMD.
• Error codes. v2 threw Error with arbitrary string messages. 4.0.1 introduces 34 structured codes in the MAPSTED-1xxx range, all surfaced via MapstedError (extends Error with a code property). See Error Codes.
• Async contract. 4.0.1 init() returns Promise<MapInstance>. v2 initialize() was sync-looking but race-prone — the change makes readiness explicit.
• element string semantics (CSS selector, not raw id). v2 and 4.0.1 both accept element: HTMLElement | string as the init target. The string form changed meaning: in v2 examples, the string was interpreted as a raw element id (e.g. element: 'map' matched <div id="map">); 4.0.1 interprets the string as a CSS selector (element: '#map'). Update v2 code accordingly: element: 'map' → element: '#map'.
• State API. 4.0.1 adds getState() and subscribe(fn) for read-only state observation (getState() returns a Promise — await it). v2 had no equivalent.
• New methods. 4.0.1 adds setAccessibilityMode(mode) and setStrictMode(enabled). For building and floor navigation, use navigateToFloorById(id) / navigateToFloorByName(name).

5. Six-step upgrade checklist

1. Update method names using the rename table in §1 above. The runtime shim warns on first call, so you can do this incrementally. Ten renames + one removal.
2. Update element string form to a CSS selector. v2 initialize({ element: 'map' }) (raw id) becomes 4.0.1 init({ element: '#map' }) (CSS selector). HTMLElement references work unchanged.
3. await every init() call. init() returns Promise<MapInstance> — capture the returned handle if you need destroy() / isReady() / state queries.
4. Wrap init() + command calls in try/catch and check err instanceof MapstedError. Map the codes you care about (MAPSTED-1001 already-initialised, MAPSTED-1010 missing propertyId, MAPSTED-1200 invalid API key, MAPSTED-1303 origin mismatch).
5. Migrate event handlers from addEventListener / removeEventListener to on / off / once. Rename MAP_MOUNTED → mapMounted and IDLE_CHANGE → idleChange. Remove every highlightStyle() call — use the highlight field on MapEntity objects instead.
6. Configure SecurityConfig. Add security.allowedOrigins to your init() options. If you previously relied on the v2 no-op default, now is the time to audit which origins you actually accept postMessage from.

Optional: opt into migration strict mode during the upgrade (setStrictMode(true) or strict: true in init() options) to turn deprecation warnings into hard errors. This ensures you have no remaining v2 call sites before the shim is removed in a future major release.

6. Where to go next

• Embed your first map — 5-minute 4.0.1 starter.
• Complete API reference
• Error codes
• Changelog
• Legacy v2 API reference — historical v2 surface for lookup.
• v3 archive — if you happen to be on v3 instead of v2, the v3 → 4.0.1 migration is a shorter walk.