Migrating to 4.0.1 (the current release) from v3

This page is the v3 → 4.0.1 migration reference. v3 to 4.0.1 is a focused upgrade — the public API surface was renamed and hardened, but v3's foundations (TypeScript, npm, element: HTMLElement | string) carry forward unchanged.

Upgrading is optional. mapi.mapsted.com keeps serving v3.0.0 directly, so your existing <script> integration keeps working 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 v2, use Migrating from v2 to 4.0.1 instead — a longer doc that also covers v2-specific changes (TS/npm/element).

Every v3 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

Ten v3 method names were renamed at the 4.0.1 boundary for clarity, casing consistency, and to align the event API with idiomatic JavaScript. One constant was removed for security.

v3 method	4.0.1 method	Notes
initialize(options)	init(options)	Now returns Promise<MapInstance> — await it.
set(options)	init(options)	v3 set() was the public alias for internal setOptions().
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, now throws)	Was a no-op stub in v3. 4.0.1 makes it throw MAPSTED-1093 on call.

Public-constant removal:

• PRIVATE_CHILD_ACTION — v3 exposed this enum by accident. 4.0.1 removes it from the public surface (CHL-27 security review). Remove the import:

  // v3 (still works via shim until a future major release, but emits a deprecation warning)
  import { PRIVATE_CHILD_ACTION } from '@mapsted/maps-js-api';
  
  // 4.0.1 — just remove the import. No replacement needed; protocol handling is internal.

2. What stays the same from v3

These v3 features carry forward unchanged:

• TypeScript types + .d.ts declarations
• mapsted.maps npm package distribution
• element: HTMLElement | string init input shape (CSS selector or direct element)
• All 14 v3 interfaces (CalculationRequest, EntityData, initializeOptions, etc.) — preserved with identical shapes in 4.0.1
• All 3 v3 enums (ActionTypes, Loader, RouteOptions)
• All 21 v3 functions (renamed where noted in §1)

4.0.1 adds 13 new interfaces, 1 new class (MapstedError), 18 new type aliases, and 6+ new functions — see the changelog for the full list.

3. init() is now async and returns MapInstance

v3's initialize(options) was synchronous (void return) and left readiness to the caller. 4.0.1's init(options) returns Promise<MapInstance>:

// v3 (fire-and-forget, no handle)
maps.initialize({ element: '#map', propertyId: 603 });

// 4.0.1 (await the handshake, use the returned MapInstance)
const map = await mapsted.maps.init({ element: '#map', propertyId: 603 });
await map.isReady();
// …later…
await map.destroy();

4. Typed event system

v3's DOM-style addEventListener / removeEventListener is replaced by typed on / off / once:

// v3 (still works via shim — same behaviour as before)
mapsted.maps.addEventListener('select', (event) => {
  console.log(event.detail);
});

// 4.0.1 (typed, discriminated-overload inference)
const unsub = mapsted.maps.on('select', (data) => {
  // data: EntityData — fully typed, no cast needed
  console.log(data.entityId);
});

// Stop listening
unsub();
// …or…
mapsted.maps.off('select', handler);

// One-time listener (new in 4.0.1)
mapsted.maps.once('load', () => console.log('ready'));

5. Structured error codes (new in 4.0.1)

v3 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):

// v3: untyped
try { maps.initialize({ propertyId: 'bad' }); }
catch (e) { console.error(e.message); } // arbitrary string

// 4.0.1: typed
import { MapstedError } from '@mapsted/maps-js-api';
try {
  await mapsted.maps.init({ propertyId: 'bad' });
} catch (err) {
  if (err instanceof MapstedError) {
    switch (err.code) {
      case 'MAPSTED-1001': /* already initialised */ break;
      case 'MAPSTED-1010': /* missing propertyId */ break;
      case 'MAPSTED-1303': /* origin mismatch */ break;
      default: console.error(err.code, err.message);
    }
  }
}

See the Error Codes reference for the full 34-entry list.

6. SecurityConfig — origin-validated postMessage (new in 4.0.1)

v3 used postMessage(..., '*') everywhere — any parent or child frame could read postMessage traffic. 4.0.1 introduces a public SecurityConfig contract for origin-locked postMessage handling:

await mapsted.maps.init({
  mapsDomain: 'https://maps.mapsted.com',
  propertyId: 603,
  security: {
    allowedOrigins: ['https://maps.mapsted.com'],
    additionalOrigins: ['https://proxy.customer.com'],
    strictMode: true,
  },
});

• SecurityConfig.strictMode defaults to true. Origin mismatches throw MAPSTED-1303 instead of silent-discard. Pass security.strictMode: false to opt out during incremental rollout.
• allowedOrigins defaults to [] (deny-all). Callers must supply at least one origin.
• additionalOrigins extends the whitelist for proxy setups.

Note on two strict modes. SecurityConfig.strictMode (origin validation, default true) is separate from migration-shim strict mode (deprecated-method behaviour, default false, toggled via setStrictMode(true) or init({ strict: true })).

See SecurityConfig for the full type.

7. Six-step upgrade checklist

1. Update method names using the rename table in §1. The runtime shim warns on first call; migrate incrementally.
2. await every init() call and capture the returned MapInstance handle.
3. Wrap init() + command calls in try/catch and check err instanceof MapstedError. Map the codes you care about.
4. Migrate event handlers from addEventListener/removeEventListener to on/off/once.
5. Remove every highlightStyle() call and drop any PRIVATE_CHILD_ACTION import.
6. Configure SecurityConfig. Add security.allowedOrigins to your init() options. Audit which origins your app actually needs to receive 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. Ensures zero v3 call sites before the shim is removed in a future major release.

8. Where to go next

• Embed your first map — 4.0.1 starter.
• Complete API reference
• Error codes
• Changelog
• v3 archive — v3 legacy reference if you need to look up the old surface while migrating.