# Upgrading the Address element

Hand-written, next to the generated reference. The generator keeps this file and does not check it. Newest first.

## 1.1.0 to 1.1.1

This patch preserves the service error when its retry wait cannot fit the request deadline. A rate-limit response with a 60-second Retry-After and the default 10-second deadline now reports FAIR_USE_CEILING instead of TIMEOUT. No retry is sent early.

Update the exact script URL and integrity together:

```html
<script
  src="https://cdn.comms.id/address/1.1.1.js"
  integrity="sha384-GdedXXgcUCVjl+m311XqwsnZqFmurzu8tprZCx/Sh991nh5Sec6aQ0e9/ZK6I1oj"
  crossorigin="anonymous"
></script>
```

The bundle is 26,924 bytes (9,120 bytes gzipped). Attributes, events and theme defaults are unchanged. Earlier exact-version files remain available with their original bytes; the major alias takes this patch when the CDN is deployed.

## 1.0.0 to 1.1.0

The element now uses the shared Comms.ID theme for default colours, borders, focus and corner radius. It inherits light/dark tokens when the host imports `@comms-id/theme/tokens.css`; without that stylesheet it uses the light defaults. Existing `--comms-id-*` overrides and `::part()` styles keep priority. Fonts still inherit from the host page.

The public attributes, events, requests and shadow isolation are unchanged. Review the new default appearance before updating a version-pinned script. The major alias `https://cdn.comms.id/address/v1.js` takes this release when the CDN is deployed; older exact-version files stay unchanged.

```html
<script
  src="https://cdn.comms.id/address/1.1.0.js"
  integrity="sha384-RIeFzFM9ak1S/1nbRxAPlECzJhrd+D6rT/ofsNqrtwaFcbnvdgmysNhEUzPFjUHH"
  crossorigin="anonymous"
></script>
```

The new file is 26,856 bytes (9,063 bytes gzipped, below the 15,000-byte limit). The element remains a CDN asset; the theme dependency is bundled into it, so a plain script install needs no npm step.

## 0.1.3 to 1.0.0

### In one line

Change the script's version and its integrity hash. Nothing else on your page changes.

### What changed

- **One behaviour you can see: the element waits 400 ms after the last key before it asks for suggestions (it was 200 ms).** The old wait was shorter than the usual gap between keys, so a person who types at an ordinary speed sent a request after almost every key, and every `suggest` request counts against the fair-use ceiling (150 requests a product a day to start). With the new wait the same person sends one `suggest` request for a pause, not one for each key. comms.id/address reports the measurement: about 4 completed addresses a day at the ceiling with 0.1.3, and about 75 with 1.0.0, for a person who types 40 words a minute. To keep the old wait, add `debounce="200"` to the element.
- **Nothing else changed.** The two files differ in one character, the default wait (200 became 400 in the bundled controller). The attributes (the `debounce` attribute still overrides the default), events, properties, parts, custom properties and content security policy needs are the same as in 0.1.3. 1.0.0 is the launch release; the 0.x releases were prereleases. The size is the same (24,312 bytes; gzipped 8,377 to 8,379 of the 15,000 allowed).
- **New URLs.** `https://cdn.comms.id/address/1.0.0.js` is new, and so is the major alias `https://cdn.comms.id/address/v1.js`, which follows the newest 1.x release (1.0.0 now). The alias `https://cdn.comms.id/address/v0.js` is not changed by this release and keeps serving 0.1.3.

### Script tag

Before (0.1.3):

```html
<script
  src="https://cdn.comms.id/address/0.1.3.js"
  integrity="sha384-9vOlQgoIOHUXk+q2aHEgtgtS85+/J6fa44XYORDQCO2jtSrlQ+EYNLywAve3RZOT"
  crossorigin="anonymous"
></script>
```

After (1.0.0):

```html
<script
  src="https://cdn.comms.id/address/1.0.0.js"
  integrity="sha384-7FPIVEPB1mntl8BfVwEi2jaTssrOQ72fsxRcWUsDr1EZgSuLVvrN/o181vMBmxcV"
  crossorigin="anonymous"
></script>
```

If you use the major alias `https://cdn.comms.id/address/v0.js`, change it to `https://cdn.comms.id/address/v1.js` to take 1.0.0. The alias cannot carry an integrity hash, because its bytes change with each release. `0.1.3.js` stays served and unchanged, so a page that is not upgraded keeps working as before.

### npm

No npm change is needed for the element: `@comms-id/address-element` is not published to npm, the element is served from the CDN only. The default wait comes from the controller, so the npm packages that run it get the same default in their next minor release: `@comms-id/address` (0.2.0 now, then 0.3.0) and, as a patch, `@comms-id/address-react` (0.2.0 now). The API does not change: only the default of `debounceMs` (200 became 400); pass `debounceMs: 200` to keep the old wait. A range such as `^0.2.0` stays on 0.2.x for a 0.x package, so to take the new default change the range to `^0.3.0`.


## 0.1.2 to 0.1.3

### In one line

Change the script's version and its integrity hash. Nothing else on your page changes.

### What changed

- **Behaviour you can see: none.** The element bundles the client runtime, which gained checks for the other products' contracts (patterns, maps, exclusive bounds) and keeps the body of a structured reply that comes with an error status. Replies and errors of this product are handled exactly as before. The attributes, events, properties, parts, custom properties and content security policy needs are the same as in 0.1.2.
- The file grew by 599 bytes (23,713 to 24,312; gzipped 8,208 to 8,377 of the 15,000 allowed).

### Script tag

Before (0.1.2):

```html
<script
  src="https://cdn.comms.id/address/0.1.2.js"
  integrity="sha384-aU3vihAETPTOKy2vDBeBQ6JIY/CNb38VunKaLXBTlr3gR1IGftVY65boSm1GBh5b"
  crossorigin="anonymous"
></script>
```

After (0.1.3):

```html
<script
  src="https://cdn.comms.id/address/0.1.3.js"
  integrity="sha384-9vOlQgoIOHUXk+q2aHEgtgtS85+/J6fa44XYORDQCO2jtSrlQ+EYNLywAve3RZOT"
  crossorigin="anonymous"
></script>
```

The major alias `https://cdn.comms.id/address/v0.js` follows the newest 0.x release (0.1.3 after this release) and needs no change. `0.1.2.js` stays served and unchanged.

### npm

No npm package changes: none of the Address packages is published yet.

## 0.1.1 to 0.1.2

### In one line

Change the script's version and its integrity hash. Nothing else on your page changes.

### What changed

- **One behaviour you can see: an outage reads as an outage.** When the service answers HTTP 502, 503 or 504 (whatever the error code), the element now says "Address search is unavailable. Try again later." and `comms-id-error` has `detail.error.outcome` of `source-unavailable`. In 0.1.1 those statuses said "Address search failed. Try again." with the outcome `failed`. An error with the code `UNAVAILABLE` already said "unavailable" and still does.
- Everything else is the same: the attributes, events, properties, parts, custom properties and content security policy needs. The file grew by 142 bytes (23,571 to 23,713; gzipped 8,158 to 8,208 of the 15,000 allowed).

### Script tag

Before (0.1.1):

```html
<script
  src="https://cdn.comms.id/address/0.1.1.js"
  integrity="sha384-Sn0Gk358v/GRuHg1LZlkXLAWq6/40J80OlD6zQnK47VpG50yTR75xvef+w2Zk6sr"
  crossorigin="anonymous"
></script>
```

After (0.1.2):

```html
<script
  src="https://cdn.comms.id/address/0.1.2.js"
  integrity="sha384-aU3vihAETPTOKy2vDBeBQ6JIY/CNb38VunKaLXBTlr3gR1IGftVY65boSm1GBh5b"
  crossorigin="anonymous"
></script>
```

The major alias `https://cdn.comms.id/address/v0.js` follows the newest 0.x release (0.1.2 after this release) and needs no change. Check the hash as in the section below: the second command, for `0.1.2.js`, must print `aU3vihAETPTOKy2vDBeBQ6JIY/CNb38VunKaLXBTlr3gR1IGftVY65boSm1GBh5b`. `0.1.0.js` and `0.1.1.js` stay served and unchanged.

### npm

No npm package changes: none of the Address packages is published yet.

## 0.1.0 to 0.1.1

### In one line

Change the script's version and its integrity hash. Nothing else on your page changes.

### What changed

- **Behaviour you can see: none.** The attributes (`relay`, `pk`, `base-url`, `label`, `name`, `placeholder`, `required`, `disabled`, `min-chars`, `debounce`, `limit`), the events (`comms-id-select`, `comms-id-error`), the properties (`value`, `address`, `client`, `signals`), the parts, the custom properties and the content security policy needs are the same as in 0.1.0.
- **Why the file differs.** The element bundles the Address client. That client gained a table of the two API hosts (LIVE `https://api.comms.id` and TEST `https://api-test.comms.id`), so the file grew by 279 bytes (23,292 to 23,571; gzipped 8,065 to 8,158 of the 15,000 allowed). The default host is still `https://api.comms.id`.
- **TEST from a page.** To call the TEST service from a page, set `base-url="https://api-test.comms.id"` on the element (public key mode: use a `pk_test_` key from a development app). The element has no `environment` attribute yet.

### Script tag

Before (0.1.0):

```html
<script
  src="https://cdn.comms.id/address/0.1.0.js"
  integrity="sha384-7sZVZZKYArCmAByXN54o0d6lZYXQ78EHIQ9DaM4Kpaz8HbTdBA+0S60itrHcaql6"
  crossorigin="anonymous"
></script>
```

After (0.1.1):

```html
<script
  src="https://cdn.comms.id/address/0.1.1.js"
  integrity="sha384-Sn0Gk358v/GRuHg1LZlkXLAWq6/40J80OlD6zQnK47VpG50yTR75xvef+w2Zk6sr"
  crossorigin="anonymous"
></script>
```

If you use the major alias `https://cdn.comms.id/address/v0.js`, change nothing: it follows the newest 0.x release (0.1.1 after this release). The alias cannot carry an integrity hash, because its bytes change with each release.

### npm

No npm package changes. `@comms-id/address-element` is not published to npm: the element is served from the CDN only. `@comms-id/address` (the client) and `@comms-id/address-react` are not published yet either; when `@comms-id/address` is published, the `environment` option is a minor change (new option, same defaults), so a consumer moves from 0.1.x to the next minor with no code change.

## Check a release yourself

The CDN manifest lists every released version with the hash of its exact bytes:

```sh
curl -s https://cdn.comms.id/manifest.json
curl -s https://cdn.comms.id/address/1.0.0.js | openssl dgst -sha384 -binary | openssl base64 -A
```

The second command, for the version you are moving to, must print the hash in that version's script tag above (for 1.0.0: `7FPIVEPB1mntl8BfVwEi2jaTssrOQ72fsxRcWUsDr1EZgSuLVvrN/o181vMBmxcV`). A released file never changes, so a page that has not been upgraded keeps working.

After the change, the element must still be defined and answer: open the page and use the field, and the element works as before. A wrong hash blocks the script; the browser console names the integrity failure.