Versioning policy

Loader versions

Address	Content	Cache
`https://api.mirac-ozdemir.com/widget.js`	The current loader (currently v1, 1.1.0).	`max-age=3600`
`https://api.mirac-ozdemir.com/widget/v1.js`	An alias pinned to v1; the same file as `/widget.js`.	`max-age=3600`
`https://api.mirac-ozdemir.com/widget/v1.1.0.js`	The immutable copy of this version (the same bytes).	`max-age=31536000, immutable`
`https://api.mirac-ozdemir.com/widget/manifest.json`	The version list, addresses and integrity hashes.	`max-age=300`

/widget.js and /widget/v1.js serve the same v1 loader; a change reaches visitors within an hour at the latest. Both remain compatible with v1: breaking changes are published at a separate address (/widget/v2.js), so a page that uses /widget.js does not move to v2 by itself. If you want to see the version explicitly in your code and make a deliberate move later, use /widget/v1.js; for full pinning, use the immutable address below.

At runtime you can read the loader’s version with window.MiracOzdemirWidget.version ("1"), .build ("1.1.0") and .features.

What is new in loader 1.1.0

All of it is backward compatible; integrations written for 1.0 keep working unchanged:

update, setInputs, calculate, reset, get, getResult, unmountAll and build/features: JavaScript API.
data-input-*, data-inputs, data-autorun, data-view: Installation.
data-accent, data-radius, data-density, data-theme="inherit", data-title, data-lazy.
Search and category widgets (data-mo-search, data-mo-category) and the <mo-calculator>, <mo-search>, <mo-category> custom elements: Widget kinds, Custom elements and SDK.
New events mo:input, mo:select; extended detail for mo:ready, mo:result, mo:error: Events.
A layout-shift fix with a placeholder skeleton, learned height and preconnect.
The iframe title is localized; console warnings are now in English.
A versioned immutable address and a manifest (SRI).

Immutable versioned URL and SRI

The versioned address (/widget/v1.1.0.js) never changes and is cached for a year; so you can have the browser verify it with a Subresource Integrity (SRI) hash: if the file differs by even one byte, the browser does not run the script. The hash is published in manifest.json:

{
  "latest": "1.1.0",
  "protocol": 1,
  "versions": [
    {
      "version": "1.1.0",
      "url": "https://api.mirac-ozdemir.com/widget/v1.1.0.js",
      "integrity": "sha384-…",
      "features": ["update", "inputs", "calculate", "reset", "inherit-theme", "kinds", "custom-elements"]
    }
  ]
}

The integrity value is abbreviated as sha384-… above; always read the real value from the manifest of the environment you use. The hash depends on the site origin the API is configured with (the only value written into the loader), so you cannot use one environment’s hash in another. The manifest is readable cross-origin.

<div data-mo-tool="kdv"></div>
<script
  src="https://api.mirac-ozdemir.com/widget/v1.1.0.js"
  integrity="sha384-…"
  crossorigin="anonymous"
  async
></script>

const base = 'https://api.mirac-ozdemir.com';
const manifest = await (await fetch(`${base}/widget/manifest.json`)).json();
if (manifest.protocol !== 1) throw new Error('Unexpected protocol');
const entry = manifest.versions.find((v) => v.version === manifest.latest);

const script = document.createElement('script');
script.src = entry.url;
script.integrity = entry.integrity;
script.crossOrigin = 'anonymous';
script.async = true;
document.head.append(script);

import { loadPinnedWidget } from '@mirac-ozdemir/widget';

const widget = await loadPinnedWidget(); // newest version in the manifest + its integrity

The SDK is not published to npm yet; see Custom elements and SDK.

The cost of pinning with SRI: a pinned loader never changes, so bug fixes and new features do not reach you until you update the hash and the address. If you want to stay current continuously, use /widget.js. If you use CSP, no extra rule is needed because the address is on the same API origin (Security and CSP).

Changes allowed within v1

v1 receives only backward-compatible changes:

bug fixes,
new optional data-* attributes,
new event types or new fields in the events’ detail,
new message types that the loader ignores today.

For this reason your event handlers should ignore fields and event types they do not know. A new loader and an old embed page (or the reverse) work together: the loader reads what is supported from the features field of the ready message and either rejects unsupported control calls or fulfils them by reloading the iframe.

Breaking changes

The following are breaking and are published with a new version (/widget/v2.js, protocol version: 2):

renaming or removing attributes or global API members,
changing event names or detail shapes,
a new protocol version,
moving the embed page to a different address scheme.

When a new version is published, v1 keeps working for as long as it is in use; the embed page stays compatible with v1 loaders (version: 1 messages) that are cached or pinned.

The embed address is part of the contract

The /{locale}/embed/{key} address and its query parameters (theme, header, id, view, accent, radius, density, autorun, i.<field>), as well as the /{locale}/embed/kit/search and /{locale}/embed/kit/category/{key} addresses, are part of the public contract; plain-iframe integrations use them directly. These parameters are not changed in incompatible ways. kit is a reserved tool key.