# Changelog

> What changed in each release of Tamr's SDKs for the web, React Native, Flutter, iOS and Android, and of @tamr/api, from each package's own CHANGELOG.

Source: https://tamr.link/docs/changelog

Each SDK's changes, from its own CHANGELOG in Tamr's repository. A version at the top of a list can be built and documented before it reaches its registry: each SDK's page shows the latest release actually published. For the API itself, `/api/v1` only grows; see [Versioning](https://tamr.link/docs/api#versioning).

## Web: @tamr/waiter-web

### 1.2.1

- The first published version with 1.2.0's look options: 1.2.0 was tagged but never reached npm or the script tag, because its
  script came out at 12.1 KB gzipped, over the 12 KB budget. The budget is now 13 KB. No code change from 1.2.0.

### 1.2.0

- More of the chat's look for your app, as new fields of the appearance (`setAppearance`, and `appearance` in `createWaiter`):
  - the colours of its parts: `headerColor`, `bubbleColor` (the diner's own messages), `buttonColor`
    (Send, Checkout and the other main buttons), `cardColor`, `mutedColor`, `lineColor` and `positiveColor`
    ("Added", "In your cart"). A filled part gets black or white words, whichever reads; muted and positive
    words are nudged until they read on your paper;
  - styles: `header` (plain or brand, the bar filled with your accent), `bubble` (soft or brand), `buttons`
    (pill, rounded or square) and `starterStyle` (chips or cards);
  - switches: `showWaiterName`, `showWelcome`, `showQuickReplies`, `showNewChat` and `showCheckout` (hide
    Checkout on the cart card when your app has its own).
  The restaurant can set each one in Settings > Waiter in your app; your app's value wins while "Allow the app
  to customise" is on. All additive.
- `showPoweredBy` is ignored: "Powered by Tamr" always shows, whatever an app or a restaurant sets.

### 1.1.1

- Opened while offline, the panel no longer shows the browser's own error page with no way out (#772).
  When the page hasn't said `ready` within 10 seconds of loading, or the browser is offline when the chat
  opens, the panel shows the shell's "The waiter couldn't open" with Try again (a new frame) and, for the
  launcher and the sheet, Close, as the app shells do. A page that answers after that takes the panel back.
  A load that failed while hidden (a preload, a background tab) is tried again when the chat is shown. With
  `debug: true` the shell says why (`[tamr] shell: the page didn't load (…)`).
- The script tag grows from 34.7 KB to 36.7 KB (11.1 to 11.7 KB gzipped, within its 12 KB budget).

### 1.1.0

- Post-meal reviews (#453): `requestReview({ orderId, dishes })` asks the diner, after an order is served, to rate each of its
  dishes (1 to 5 stars), held until the chat is ready like `sendCart`. The order must be one your backend
  sent (`POST /api/v1/sdk/orders`) for this diner. The chat opens its "How was your order?" sheet when it's
  shown, and the new `review.submitted` event says what they rated: the order and each dish's review id and
  stars, never words. The `review.submitted` webhook stays the source of truth for your backend.
- The contract's check where the site's values enter the bridge (#614): every setter, `sendCart`,
  `chat.send` and the values given to `createWaiter`. With `debug: true` a value the contract refuses (a
  colour that isn't `#RRGGBB`, seven starters, a 41-character table) throws a `TypeError` at the call,
  naming the message, the field and the rule, never the value. A minor version because code that passed
  such a value before now throws in debug mode.
- Without `debug`, a bad patch field (`appearance`, `text`) is sent as it is and the page drops that field
  alone; any other refused message isn't sent. Either way one line, `[tamr] shell: appearance: dropped
  accent (format)` or `[tamr] shell: starters: not sent: items (count)`, goes to `onLog` or `console.warn`
  once per message type and field, even outside debug mode. Nothing else changes on the wire.
- The script tag grows from 23.6 KB to 32.7 KB (7.9 to 10.6 KB gzipped, within its 12 KB budget): the
  generated check and the reply's repair (#676) now ship with it.
- The cart handler's reply is checked before it's posted (#676), so a reply the page would refuse no
  longer leaves the cart to time out. A bad field is repaired, never stopped on: a refused `error.message`
  or line `message` is trimmed as JavaScript's `trim()` does, then cut to 300 or 200 code points (never
  inside an emoji), or dropped if only spaces are left; `lines` and `unmapped` keep their first 50; a line
  or unmapped entry with a bad id is dropped. One line per field, `[tamr] shell: reply: trimmed
  error.message (length)`, goes to `onLog` or `console.warn` once, never with the value. A reply still
  refused after that goes as `failed` to the same `replyTo`. A good reply is posted as before.
- On phones the chat panel now fits the space above the keyboard, and a phone in landscape gets the
  full-screen panel (#681).
- `setGoal(goal)` (#450): the diner's nutrition goal as your app keeps it, per meal (`{ mode: "cutting",
  kcal: 600 }`; a mode with no number checks nothing until the diner gives one). Kept and sent again after
  every `ready`, like `setRestrictions`. While it's set it wins over the one the diner keeps, and the waiter
  says to change it in your app; `setGoal(null)` stops setting one. `Goal` and `NutritionMode` are exported.
- Treats on the house (#455): a `CartLine` in `cart.add` can carry an optional `treat` (`treatId`,
  `expiresAt`). Price that line at zero in your checkout, and redeem it from your backend once the order is
  placed (`docs/sdk/orders.md`). Additive: the field is forwarded as it comes.
- An app can hide Tamr's review ask, take-home suggestions and treats on the house (#726), as it hides voice:
  `appearance.hideReviews`, `hideRetailSuggestions` and `hideLoyalty`. Off only: the restaurant's own switches
  win, and an app never turns one on. With reviews hidden, `requestReview` answers `not_allowed`. Additive.
- `order.cancelled` (#743): the page tells your app when an order it heard placed ends unserved (declined,
  cancelled or expired), with `orderId` and `status`. Also a webhook. Additive.
- `order.placed` can carry `test: true` (#742): a test key's pickup, checked and priced but never sent to the
  restaurant. Additive: the field is forwarded as it comes.

### 1.0.1

The first published version: 1.0.0 was tagged but never published, because the release's test step
couldn't run the tests outside the monorepo. The SDK is unchanged from 1.0.0.

- The tests read the SDK's own TypeScript settings (`src/__tests__/tsconfig.json`), so they run with only
  the SDK's packages installed, as the release's test step does.

### 1.0.0

The Web SDK (#442).

- `createWaiter`: Tamr's hosted waiter page in an iframe, as a launcher bubble and panel, a side sheet,
  or inline in an element the site gives; in a shadow root with constructed stylesheets.
- The bridge (ADR 0005, 0006): `host.hello` and `ready`, `host.hello` again on a `ready` that isn't its
  reply, an outbox until `ready`, what the site set sent again after every `ready`, messages taken only
  from the frame on Tamr's origin and once each.
- The page's requests answered within 15 seconds: `identity.request` (`setIdentityProvider`), the cart
  (`onCartAdd`, `onCartUpdate`, `onCartRemove`), and `payment.open`, opened in a new tab only when
  https, with an error when the browser blocks the tab.
- `on(type, …)` for every page event; `open`, `close`, `preload`, `destroy`; the setters for locale,
  appearance, text, theme, context, starters and restrictions.
- Visibility from the panel and the document; a chat hidden for 10 minutes is released.
- Debug mode: `[tamr] page …` and `[tamr] shell: …` lines to `onLog` or the console.
- The script tag on `tamr.link/sdk/web/v1.js`, with `window.TamrWaiter` and a zero-code launcher for
  keys in guest mode.

### 0.0.1

Placeholder, the first release through the pipeline (`pnpm sdk:release web`, npm trusted publishing). Does nothing; deprecated once it installs.

### 0.0.0

Placeholder, published by hand to set up npm trusted publishing (docs/sdk/release.md). Does nothing.

## React Native: @tamr/waiter-react-native

### 1.3.0

- More of the chat's look for your app, as new fields of the appearance (`setAppearance`, and `appearance` in `createWaiter`):
  - the colours of its parts: `headerColor`, `bubbleColor` (the diner's own messages), `buttonColor`
    (Send, Checkout and the other main buttons), `cardColor`, `mutedColor`, `lineColor` and `positiveColor`
    ("Added", "In your cart"). A filled part gets black or white words, whichever reads; muted and positive
    words are nudged until they read on your paper;
  - styles: `header` (plain or brand, the bar filled with your accent), `bubble` (soft or brand), `buttons`
    (pill, rounded or square) and `starterStyle` (chips or cards);
  - switches: `showWaiterName`, `showWelcome`, `showQuickReplies`, `showNewChat` and `showCheckout` (hide
    Checkout on the cart card when your app has its own).
  The restaurant can set each one in Settings > Waiter in your app; your app's value wins while "Allow the app
  to customise" is on. All additive.
- `showPoweredBy` is ignored: "Powered by Tamr" always shows, whatever an app or a restaurant sets.

### 1.2.1

- On Android a chat opened while offline shows "The waiter couldn't open" and Try again, instead of a
  spinner that never ended (#774): the webview starts its own error page right after the load error, and
  that start no longer takes the failed state back to loading. Try again loads the page in a new webview.
  iOS is unchanged.

### 1.2.0

- Post-meal reviews (#453): `requestReview({ orderId, dishes })` asks the diner, after an order is served, to rate each of its
  dishes (1 to 5 stars), held until the chat is ready like `sendCart`. The order must be one your backend
  sent (`POST /api/v1/sdk/orders`) for this diner. The chat opens its "How was your order?" sheet when it's
  shown, and the new `review.submitted` event says what they rated: the order and each dish's review id and
  stars, never words. The `review.submitted` webhook stays the source of truth for your backend.
- The contract's check where the app's values enter the bridge (#614): every setter, `sendCart`,
  `chat.send` and the values given to `createWaiter`. In a development build (`__DEV__`) a value the
  contract refuses (a colour that isn't `#RRGGBB`, seven starters, a 41-character table) throws a
  `TypeError` at the call, naming the message, the field and the rule, never the value. A minor version
  because code that passed such a value before now throws in development.
- A release build sends a bad patch field (`appearance`, `text`) as it is, and the page drops that field
  alone; any other refused message isn't sent. Either way one line, `[tamr] shell: appearance: dropped
  accent (format)` or `[tamr] shell: starters: not sent: items (count)`, goes to `onLog` or `console.warn`
  once per message type and field, even without `debug`. Nothing else changes on the wire.
- The cart handler's reply is checked before it's posted (#676), so a reply the page would refuse no
  longer leaves the cart to time out. A bad field is repaired, never stopped on: a refused `error.message`
  or line `message` is trimmed as JavaScript's `trim()` does, then cut to 300 or 200 code points (never
  inside an emoji), or dropped if only spaces are left; `lines` and `unmapped` keep their first 50; a line
  or unmapped entry with a bad id is dropped. One line per field, `[tamr] shell: reply: trimmed
  error.message (length)`, goes to `onLog` or `console.warn` once, never with the value. A reply still
  refused after that goes as `failed` to the same `replyTo`. A good reply is posted as before.
- On iOS an app opened while offline shows the "couldn't open" screen and Try again, instead of a stale,
  unstyled page that never recovered: the page itself is requested with `Cache-Control: no-cache`, so
  WKWebView no longer serves its cached copy (#675). Android is unchanged.
- When the app goes to the background (`AppState` `background`), a shown chat is told it's hidden at
  once, so the page stops acting as shown right away; on iOS it used to learn it minutes later, when iOS
  suspended the app (#678). Coming back tells it it's shown again, as before.
- `setGoal(goal)` (#450): the diner's nutrition goal as your app keeps it, per meal (`{ mode: "cutting",
  kcal: 600 }`; a mode with no number checks nothing until the diner gives one). Kept and sent again after
  every `ready`, like `setRestrictions`. While it's set it wins over the one the diner keeps, and the waiter
  says to change it in your app; `setGoal(null)` stops setting one. `Goal` and `NutritionMode` are exported.
- `TamrWaiterSheet` takes `insets` for the sheet too: on Android, where the sheet fills the screen, the
  composer now stays above the navigation bar instead of under it (#449's device run). Pass
  `insets={useSafeAreaInsets()}` as for the full page; iOS is unchanged.
- On Android `TamrWaiterSheet` keeps its Close bar below the status bar too (`insets.top`): it sat in the
  status bar, where a tap on it didn't reach the button (#732's device run).
- On iOS the sheet's composer stays above the keyboard: it was hidden behind it (#449's device run,
  iPhone 14 on iOS 27). The host's full page also keeps its header on screen while typing.
- Treats on the house (#455): a `CartLine` in `cart.add` can carry an optional `treat` (`treatId`,
  `expiresAt`). Price that line at zero in your checkout, and redeem it from your backend once the order is
  placed (`docs/sdk/orders.md`). Additive: the field is forwarded as it comes.
- With `expo-application` installed (an optional peer), the app's bundle id or package name goes to Tamr (#615), so
  the app key's list of app ids is checked: a key used from an app it doesn't list is logged, never refused.
- An app can hide Tamr's review ask, take-home suggestions and treats on the house (#726), as it hides voice:
  `appearance.hideReviews`, `hideRetailSuggestions` and `hideLoyalty`. Off only: the restaurant's own switches
  win, and an app never turns one on. With reviews hidden, `requestReview` answers `not_allowed`. Additive.
- Debug mode makes the webview inspectable only in a development build (`__DEV__`, #738): a release build with
  `debug: true` still logs, but can't be inspected, since that would expose the diner's session.
- `order.cancelled` (#743): the page tells your app when an order it heard placed ends unserved (declined,
  cancelled or expired), with `orderId` and `status`. Also a webhook. Additive.
- `order.placed` can carry `test: true` (#742): a test key's pickup, checked and priced but never sent to the
  restaurant. Additive: the field is forwarded as it comes.

### 1.1.0

First release through the release pipeline. Reads the pickup fields on `order.placed` (`fulfilment`,
`pickupAt`, `pickupCode`) and the `awaiting_payment` status (#599).

### 1.0.0

The React Native SDK (#444).

- `createWaiter`: Tamr's hosted waiter page in a webview, with the Web SDK's names. Preloaded and kept warm
  between opens; a hidden chat is released after 10 minutes and on a memory warning, and loads again when
  the app comes back.
- `TamrWaiterHost` (always mounted at the app's root, off screen while hidden), `TamrWaiterSheet` and
  `TamrWaiterView`, closed by the page's `close`, the Close bar and Android's back button.
- The bridge (ADR 0005, 0006): `host.hello` and `ready`, `host.hello` again on a `ready` that isn't its
  reply, messages held until `ready` (kept across a reload and a release), what the app set sent again after
  every `ready`, each message taken once, and only from Tamr's page.
- The page's requests answered within 15 seconds: `identity.request` (`setIdentityProvider`), the cart
  (`onCartAdd`, `onCartUpdate`, `onCartRemove`), and `payment.open`, opened only when https, in
  `expo-web-browser`'s in-app browser when the app has it, else the system browser. The page is told again
  that it's shown when the app comes back, so it reads a payment's status.
- `on(type, …)` for every page event; the setters for locale, appearance, text, theme, context, starters
  and restrictions.
- An Expo config plugin for the microphone's permission text and Android permissions; nothing for the
  camera.
- Debug mode: `[tamr] page …` and `[tamr] shell: …` lines to `onLog` or the console.

## Flutter: tamr_waiter

### 1.2.0

- More of the chat's look for your app, as new fields of the appearance (`setAppearance`, and `appearance` on `TamrWaiterController`):
  - the colours of its parts: `headerColor`, `bubbleColor` (the diner's own messages), `buttonColor`
    (Send, Checkout and the other main buttons), `cardColor`, `mutedColor`, `lineColor` and `positiveColor`
    ("Added", "In your cart"). A filled part gets black or white words, whichever reads; muted and positive
    words are nudged until they read on your paper;
  - styles: `header` (plain or brand, the bar filled with your accent), `bubble` (soft or brand), `buttons`
    (pill, rounded or square) and `starterStyle` (chips or cards);
  - switches: `showWaiterName`, `showWelcome`, `showQuickReplies`, `showNewChat` and `showCheckout` (hide
    Checkout on the cart card when your app has its own).
  The restaurant can set each one in Settings > Waiter in your app; your app's value wins while "Allow the app
  to customise" is on. All additive.
- `showPoweredBy` is ignored: "Powered by Tamr" always shows, whatever an app or a restaurant sets.

### 1.1.0

- Post-meal reviews (#453): `requestReview(ReviewRequestData)` asks the diner, after an order is served, to rate each of its
  dishes (1 to 5 stars), held until the chat is ready like `sendCart`. The order must be one your backend
  sent (`POST /api/v1/sdk/orders`) for this diner. The chat opens its "How was your order?" sheet when it's
  shown, and the new `review.submitted` event says what they rated: the order and each dish's review id and
  stars, never words. The `review.submitted` webhook stays the source of truth for your backend.
- The contract's check where the app's values enter the bridge (#614): every setter, `sendCart`,
  `sendMessage`, `send` and the values given to the controller. In a debug build a value the contract
  refuses (a colour that isn't `#RRGGBB`, seven starters, a 41-character table) throws an `AssertionError`
  at the call, naming the message, the field and the rule, never the value. A minor version because code
  that passed such a value before now throws in debug.
- A release build sends a bad patch field (`appearance`, `text`) as it is, and the page drops that field
  alone; any other refused message isn't sent. Either way one line, `[tamr] shell: appearance: dropped
  accent (format)` or `[tamr] shell: starters: not sent: items (count)`, goes to `onLog` or `debugPrint`
  once per message type and field, even without `debug`. Nothing else changes on the wire.
- The cart handler's reply is checked before it's posted (#676), so a reply the page would refuse no
  longer leaves the cart to time out. A bad field is repaired, never stopped on: a refused `error.message`
  or line `message` is trimmed as JavaScript's `trim()` does, then cut to 300 or 200 code points (never
  inside an emoji), or dropped if only spaces are left; `lines` and `unmapped` keep their first 50; a line
  or unmapped entry with a bad id is dropped. One line per field, `[tamr] shell: reply: trimmed
  error.message (length)`, goes to `onLog` or `debugPrint` once, never with the value. A reply still
  refused after that goes as `failed` to the same `replyTo`. A good reply is posted as before.
- An iOS app opened while offline now shows the shell's "couldn't open" screen and Try again, instead of a
  stale, unstyled page that never recovers (#675): on iOS the page itself is loaded without WebKit's cache, on the
  first load, Try again and the load after a dead web process. Its images and scripts keep the normal cache.
  Android is unchanged.
- `setGoal(goal)` (#450): the diner's nutrition goal as your app keeps it, per meal
  (`Goal(mode: NutritionMode.cutting, kcal: 600)`; a mode with no number checks nothing until the diner
  gives one). Kept and sent again after every `ready`, like `setRestrictions`. While it's set it wins over
  the one the diner keeps, and the waiter says to change it in your app; `setGoal(null)` stops setting one.
- On Android the chat follows the system font size (`textZoom`), as the Kotlin SDK does. Before, it stayed
  at 100% while the app's own text grew (#449's device run).
- It also follows a font size change made while the chat is open, or while it was closed, as the Kotlin
  SDK's `onConfigurationChanged` does (#677 review).
- Treats on the house (#455): a `CartLine` in `cart.add` can carry an optional `treat` (`treatId`,
  `expiresAt`). Price that line at zero in your checkout, and redeem it from your backend once the order is
  placed (`docs/sdk/orders.md`). Additive: the field is forwarded as it comes.
- On Android the sheet keeps the page above the navigation bar: its footer sat under it (#732's device run).
- Try again after "couldn't open" shows the page it loads. On Android the view stayed blank: the new webview
  updated the released one's widget instead of replacing it (#732's device run).
- From 1.0.2, which was never published:
  - **Android needs the Android Gradle Plugin 8.x for now** (#668). `flutter_inappwebview_android` 1.1.3 doesn't build on
    AGP 9, which Flutter 3.47's template gives a new app. The README says how to set it back to 8.x. This was already
    the case for 1.0.x; it's now written down.
  - CI builds the example's Android debug APK, so a change like this can't go unnoticed again.
- An app can hide Tamr's review ask, take-home suggestions and treats on the house (#726), as it hides voice:
  `appearance.hideReviews`, `hideRetailSuggestions` and `hideLoyalty`. Off only: the restaurant's own switches
  win, and an app never turns one on. With reviews hidden, `requestReview` answers `not_allowed`. Additive.
- Debug mode makes the webview inspectable on Android only in a debug build of the app (`kDebugMode`, #738):
  a release build with `debug: true` still logs, but `chrome://inspect` can't reach it.
- `order.cancelled` (#743): the page tells your app when an order it heard placed ends unserved (declined,
  cancelled or expired), with `orderId` and `status`. Also a webhook. Additive.
- `order.placed` can carry `test: true` (#742): a test key's pickup, checked and priced but never sent to the
  restaurant. Additive: the field is forwarded as it comes.
- **On the iOS 18.4 and 18.5 simulators the app stops at launch** (#768): `Library not loaded:
  /usr/lib/swift/libswiftWebKit.dylib`, from the webview plugin's link to WebKit's Swift overlay. It's those
  simulator runtimes, with any Xcode, not iPhones. The README says which simulators to use and how to run on
  18.4 anyway; no change in your app. CI now builds the example for the iOS simulator and fails if anything
  besides the plugin links that library.

### 1.0.1

First release through the release pipeline; no change from 1.0.0.

### 1.0.0

The Flutter SDK (#443).

- `TamrWaiterController`: Tamr's hosted waiter page in a webview, preloaded and kept warm between opens; a
  hidden chat is released after 10 minutes, under memory pressure and, on Android, in the background.
- `TamrWaiterSheet`, `TamrWaiterPage` and `TamrWaiterView`, closed by the page's `close`.
- The bridge (ADR 0005, 0006): `host.hello` and `ready`, `host.hello` again on a `ready` that isn't its
  reply, messages held until `ready` (kept across a reload and a release), what the app set sent again
  after every `ready`, each message taken once.
- The page's requests answered within 15 seconds: `identity.request` (`setIdentityProvider`), the cart
  (`onCartAdd`, `onCartUpdate`, `onCartRemove`), and `payment.open`, opened in the in-app browser only
  when https. The page is told again that it's shown when the app resumes, so it reads a payment's
  status.
- `on(type, …)` for every page event; the setters for locale, appearance, text, theme, context, starters
  and restrictions.
- The microphone only through the app's own permission flow, never the camera.
- Debug mode: `[tamr] page …` and `[tamr] shell: …` lines to `onLog` or `debugPrint`.

Known limitation: `flutter_inappwebview` 6.1.5 has no Swift Package Manager support yet, so an iOS build
warns that this "will become an error in a future version of Flutter". It builds with CocoaPods as before.

## iOS: TamrWaiter

### 1.2.0

- More of the chat's look for your app, as new fields of the appearance (`setAppearance`, and `appearance` on `TamrWaiterController`):
  - the colours of its parts: `headerColor`, `bubbleColor` (the diner's own messages), `buttonColor`
    (Send, Checkout and the other main buttons), `cardColor`, `mutedColor`, `lineColor` and `positiveColor`
    ("Added", "In your cart"). A filled part gets black or white words, whichever reads; muted and positive
    words are nudged until they read on your paper;
  - styles: `header` (plain or brand, the bar filled with your accent), `bubble` (soft or brand), `buttons`
    (pill, rounded or square) and `starterStyle` (chips or cards);
  - switches: `showWaiterName`, `showWelcome`, `showQuickReplies`, `showNewChat` and `showCheckout` (hide
    Checkout on the cart card when your app has its own).
  The restaurant can set each one in Settings > Waiter in your app; your app's value wins while "Allow the app
  to customise" is on. All additive.
- `showPoweredBy` is ignored: "Powered by Tamr" always shows, whatever an app or a restaurant sets.

### 1.1.0

- Post-meal reviews (#453): `requestReview(orderId:dishes:)` asks the diner, after an order is served, to rate each of its
  dishes (1 to 5 stars), held until the chat is ready like `sendCart`. The order must be one your backend
  sent (`POST /api/v1/sdk/orders`) for this diner. The chat opens its "How was your order?" sheet when it's
  shown, and the new `review.submitted` event says what they rated: the order and each dish's review id and
  stars, never words. The `review.submitted` webhook stays the source of truth for your backend.
- The contract's check where the app's values enter the bridge (#614): every setter, `sendCart`,
  `sendMessage`, `send` and the values given to the controller. In a Debug build a value the contract
  refuses (a colour that isn't `#RRGGBB`, seven starters, an allergen made with `Allergen(rawValue:)` that
  the contract doesn't know) stops at the call with `assertionFailure`, naming the message, the field and
  the rule, never the value. A minor version because code that passed such a value before now stops a
  Debug build.
- A Release build sends a bad patch field (`appearance`, `text`) as it is, and the page drops that field
  alone; any other refused message isn't sent. Either way one line, `[tamr] shell: appearance: dropped
  accent (format)` or `[tamr] shell: starters: not sent: items (count)`, goes to `onLog` or the system log
  (as an error) once per message type and field, even without `debug`. Nothing else changes on the wire.
- The cart handler's reply is checked before it's posted (#676), so a reply the page would refuse no
  longer leaves the cart to time out. A bad field is repaired, never stopped on: a refused `error.message`
  or line `message` is trimmed as JavaScript's `trim()` does, then cut to 300 or 200 code points (never
  inside an emoji), or dropped if only spaces are left; `lines` and `unmapped` keep their first 50; a line
  or unmapped entry with a bad id is dropped. One line per field, `[tamr] shell: reply: trimmed
  error.message (length)`, goes to `onLog` or the system log (as an error) once, never with the value. A
  reply still refused after that goes as `failed` to the same `replyTo`. A good reply is posted as before.
- An iOS app opened while offline now shows the shell's "couldn't open" screen and Try again, instead of a
  stale, unstyled page that never recovers (#675): the page itself is loaded without WebKit's cache, on the
  first load, Try again and the load after a dead web process. Its images and scripts keep the normal cache.
- `setGoal(_:)` (#450): the diner's nutrition goal as your app keeps it, per meal (`Goal(mode: .cutting,
  kcal: 600)`; a mode with no number checks nothing until the diner gives one). Kept and sent again after
  every `ready`, like `setRestrictions`. While it's set it wins over the one the diner keeps, and the waiter
  says to change it in your app; `setGoal(nil)` stops setting one.
- Treats on the house (#455): a `CartLine` in `cart.add` can carry an optional `treat` (`treatId`,
  `expiresAt`). Price that line at zero in your checkout, and redeem it from your backend once the order is
  placed (`docs/sdk/orders.md`). Additive: the field is forwarded as it comes.
- The app's bundle id goes to Tamr with the first message and every call (#615), so the app key's list of app ids is
  checked: a key used from an app it doesn't list is logged, never refused. List your bundle id on the key.
- An app can hide Tamr's review ask, take-home suggestions and treats on the house (#726), as it hides voice:
  `appearance.hideReviews`, `hideRetailSuggestions` and `hideLoyalty`. Off only: the restaurant's own switches
  win, and an app never turns one on. With reviews hidden, `requestReview` answers `not_allowed`. Additive.
- Debug mode makes the web view inspectable only in a Debug build of the app (#738): a Release build with
  `debug: true` still logs, but Safari's Web Inspector can't reach it, since it would expose the diner's session.
- `order.cancelled` (#743): the page tells your app when an order it heard placed ends unserved (declined,
  cancelled or expired), with `orderId` and `status`. Also a webhook. Additive.
- The shell no longer links `libswiftWebKit.dylib`: it sent its messages through the Swift overlay's
  `callAsyncJavaScript`, and now calls WebKit's own method. The iOS 18.4 and 18.5 simulator runtimes lack
  that library at the path the app looks for, so an app linking it died at launch there (found in #732's
  device run). Phones and the other simulators have it (#768); 1.0.0 apps were affected on those two
  simulators only.
- `order.placed` can carry `test: true` (#742): a test key's pickup, checked and priced but never sent to the
  restaurant. Additive: the field is forwarded as it comes.

### 1.0.0

The iOS SDK (#446). iOS 16 or later, Xcode 16 or later (Swift 6), no dependencies. Installs with Swift
Package Manager from `https://github.com/abiroot/tamr-waiter-ios`.

- `TamrWaiterController`: Tamr's hosted waiter page in a `WKWebView`, with the Web SDK's names. Preloaded
  and kept warm between opens; a hidden chat is released after 10 minutes and on a memory warning, and loads
  again when the app comes back. A hidden chat waits parked at zero size in the app's key window, so iOS
  doesn't suspend its page (a web view in no window is suspended on an iPhone, #446).
- `TamrWaiterViewController` (a page sheet, a full page or a screen of a navigation stack) and
  `TamrWaiterView` (SwiftUI), closed by the page's `close`.
- The bridge (ADR 0005, 0006): `TamrBridge` in the page's world before the first load, messages taken only
  from the main frame on Tamr's origin, replies with `callAsyncJavaScript(arguments:)`; `host.hello` and
  `ready`, `host.hello` again on a `ready` that isn't its reply, messages held until `ready` (kept across a
  reload and a release), what the app set sent again after every `ready`, each message taken once.
- The page's requests answered within 15 seconds: `identity.request` (`setIdentityProvider`), the cart
  (`onCartAdd`, `onCartUpdate`, `onCartRemove`), and `payment.open`, opened in `SFSafariViewController` only
  when https. The page is told again that it's shown when the diner closes it and when the app comes back,
  so it reads a payment's status.
- `on(_:_:)` for every page event; the setters for locale, appearance, text, theme, context, starters and
  restrictions.
- The microphone only through `onMicrophonePermission`, for Tamr's page alone; never the camera.
- Debug mode: `[tamr] page …` and `[tamr] shell: …` lines to `onLog` or the system log, and the web view
  inspectable.

## Android: link.tamr:waiter-android

### 1.2.0

- More of the chat's look for your app, as new fields of the appearance (`setAppearance`, and `appearance` on `TamrWaiterController`):
  - the colours of its parts: `headerColor`, `bubbleColor` (the diner's own messages), `buttonColor`
    (Send, Checkout and the other main buttons), `cardColor`, `mutedColor`, `lineColor` and `positiveColor`
    ("Added", "In your cart"). A filled part gets black or white words, whichever reads; muted and positive
    words are nudged until they read on your paper;
  - styles: `header` (plain or brand, the bar filled with your accent), `bubble` (soft or brand), `buttons`
    (pill, rounded or square) and `starterStyle` (chips or cards);
  - switches: `showWaiterName`, `showWelcome`, `showQuickReplies`, `showNewChat` and `showCheckout` (hide
    Checkout on the cart card when your app has its own).
  The restaurant can set each one in Settings > Waiter in your app; your app's value wins while "Allow the app
  to customise" is on. All additive.
- `showPoweredBy` is ignored: "Powered by Tamr" always shows, whatever an app or a restaurant sets.

### 1.1.0

- Post-meal reviews (#453): `requestReview(orderId, dishes)` asks the diner, after an order is served, to rate each of its
  dishes (1 to 5 stars), held until the chat is ready like `sendCart`. The order must be one your backend
  sent (`POST /api/v1/sdk/orders`) for this diner. The chat opens its "How was your order?" sheet when it's
  shown, and the new `review.submitted` event says what they rated: the order and each dish's review id and
  stars, never words. The `review.submitted` webhook stays the source of truth for your backend.
- The contract's check where the app's values enter the bridge (#614): every setter, `sendCart`,
  `sendMessage`, `send` and the constructor's values. In a debuggable app (its `FLAG_DEBUGGABLE`, read once
  when the controller is made) a value the contract refuses (a colour that isn't `#RRGGBB`, seven starters,
  a 41-character table) throws `TamrWaiterException` with the new `Code.BAD_VALUE` at the call, naming the
  message, the field and the rule, never the value. A minor version because code that passed such a value
  before now throws in a debuggable app.
- A release build sends a bad patch field (`appearance`, `text`) as it is, and the page drops that field
  alone; any other refused message isn't sent. Either way one line, `[tamr] shell: appearance: dropped
  accent (format)` or `[tamr] shell: starters: not sent: items (count)`, goes to `onLog` or `Log.w` once per
  message type and field, even without `debug`. Nothing else changes on the wire.
- The public API only gains `TamrWaiterException.Code.BAD_VALUE`.
- The cart handler's reply is checked before it's posted (#676), so a reply the page would refuse no
  longer leaves the cart to time out. A bad field is repaired, never stopped on: a refused `error.message`
  or line `message` is trimmed as JavaScript's `trim()` does, then cut to 300 or 200 code points (never
  inside an emoji), or dropped if only spaces are left; `lines` and `unmapped` keep their first 50; a line
  or unmapped entry with a bad id is dropped. One line per field, `[tamr] shell: reply: trimmed
  error.message (length)`, goes to `onLog` or `Log.w` once, never with the value. A reply still refused
  after that goes as `failed` to the same `replyTo`. A good reply is posted as before.
- `setGoal(goal)` (#450): the diner's nutrition goal as your app keeps it, per meal
  (`Goal(NutritionMode.CUTTING, kcal = 600)`; a mode with no number checks nothing until the diner gives
  one). Kept and sent again after every `ready`, like `setRestrictions`. While it's set it wins over the one
  the diner keeps, and the waiter says to change it in your app; `setGoal(null)` stops setting one. The
  public API gains `setGoal` and the generated `Goal`, `GoalData`, `GoalMessage` and `NutritionMode`.
- Treats on the house (#455): a `CartLine` in `cart.add` can carry an optional `treat` (`treatId`,
  `expiresAt`). Price that line at zero in your checkout, and redeem it from your backend once the order is
  placed (`docs/sdk/orders.md`). Additive: the field is forwarded as it comes.
- The app's package name goes to Tamr with the first message and every call (#615), so the app key's list of app ids
  is checked: a key used from an app it doesn't list is logged, never refused. List your package name on the key.
- An app can hide Tamr's review ask, take-home suggestions and treats on the house (#726), as it hides voice:
  `appearance.hideReviews`, `hideRetailSuggestions` and `hideLoyalty`. Off only: the restaurant's own switches
  win, and an app never turns one on. With reviews hidden, `requestReview` answers `not_allowed`. Additive.
- Debug mode makes the WebView inspectable only in a debuggable build of the app (#738): a release build with
  `debug = true` still logs, but `chrome://inspect` can't reach it, since it would expose the diner's session.
- `order.cancelled` (#743): the page tells your app when an order it heard placed ends unserved (declined,
  cancelled or expired), with `orderId` and `status`. Also a webhook. Additive.
- `order.placed` can carry `test: true` (#742): a test key's pickup, checked and priced but never sent to the
  restaurant. Additive: the field is forwarded as it comes.

### 1.0.0

The Android SDK (#447): `link.tamr:waiter-android`, and `link.tamr:waiter-android-compose` for Compose.
minSdk 26, apps on compileSdk 35 or later, AGP 8.6 or later, Kotlin 2.1 or later, and an Android System
WebView with `WEB_MESSAGE_LISTENER`. Raising one of these is a major version.

- `TamrWaiterController`: Tamr's hosted waiter page in a `WebView`, with the Web SDK's names. Made once and
  kept in a `ViewModel`; preloaded and kept warm between opens. A hidden chat is released after 10 minutes,
  when Android asks for memory and when its renderer dies, and loads again on the next open or preload.
- `TamrWaiterView` (Views, no Compose needed), and in `waiter-android-compose` the `TamrWaiterView`,
  `TamrWaiterSheet` and `TamrWaiterScreen` composables, closed by the page's `close` and by Android's back.
  A rotation doesn't tell the page it was hidden, so a reply or a voice turn isn't cut.
- The bridge (ADR 0005, 0006): `TamrBridge` from `addWebMessageListener` before the first load, messages
  taken only from the main frame on Tamr's origin, replies through the document's own reply proxy;
  `host.hello` and `ready`, `host.hello` again on a `ready` that isn't its reply, messages held until
  `ready` (kept across a reload and a release), what the app set sent again after every `ready`, each
  message taken once.
- The page's requests answered within 15 seconds: `identity.request` (`setIdentityProvider`), the cart
  (`onCartAdd`, `onCartUpdate`, `onCartRemove`), and `payment.open`, opened in a Custom Tab only when https
  (anything else is `not_allowed` and never reaches the WebView). The page is told again that it's shown
  when the app's Activity resumes, so it reads a payment's status when the diner comes back.
- `on(type)` for every page event, with a remover that is safe from any thread; the setters for locale,
  appearance, text, theme, context, starters and restrictions. Every other method is for the main thread
  and says so when called from another.
- The microphone only through `onMicrophonePermission`, for Tamr's page alone; never the camera.
- Debug mode: `[tamr] page …` and `[tamr] shell: …` lines to `onLog` or `Log.d` (tag `TamrWaiter`), and the
  WebView inspectable in `chrome://inspect`.

## The API client: @tamr/api

### 1.3.0

- `catalogMenu` (`GET /api/v1/catalog/menu`, Server API): one of the restaurant's published menus, read by your
  backend with a secret key that has the new `catalog:read` permission. Name a `branch` and a `mode`, or a `menu`
  by id or slug. The dishes are exactly what `GET /api/v1/menu` gives an app at that branch and mode (prices,
  sizes, choices, availability and your ids, a branch's own winning), and `CatalogMenu` adds `menuId`,
  `menuSlug`, `modes`, `branch`, `version` (the latest version Tamr recorded, 0 before the first) and
  `updatedAt`. The answer carries an `ETag`; send it back in `If-None-Match` from your own `fetch` to get a 304.
- The `menu.changed` webhook: a menu changed, read it again. `MenuChangedEvent` carries `menuId`, `menuSlug`,
  `published`, `modes`, `branches` (`branchId`, `branch`), `version`, `reason` (`content`, `external_ids`,
  `back_on_sale`; an open list), `changedAt` and, when Tamr can tell, `dishIds`.
- Pickup reads the branch's own pickup menu first: `mode: "pickup"` serves a menu set to pickup before the
  delivery menu and the dine-in one, in `menu` and every route that takes a mode.
- Where orders go for each way of ordering (ADR 0013): `WaiterFace` gains `ordersGoToByMode`, with
  `dine_in`, `pickup` and `delivery` each `tamr` or `app_cart` (open lists), every way filled in, when the
  restaurant sends the ways of ordering to different places. Left out otherwise; `ordersGoTo` stays the
  restaurant-wide value. Read `ordersGoToByMode?.[mode] ?? ordersGoTo`. Optional.

### 1.2.0

- The restaurant's settings for the waiter in its app (`app` in `GET /api/v1/waiter`) carry its new look
  options: `AppLook` gains the part colours (`headerColor`, `bubbleColor`, `buttonColor`, `cardColor`,
  `mutedColor`, `lineColor`, `positiveColor`) and styles (`header`, `bubble`, `buttons`, `starterStyle`, all
  open lists), and `AppShown` gains `showWaiterName`, `showWelcome`, `showQuickReplies`, `showNewChat` and
  `showCheckout`. All optional.

### 1.1.1

- First release through the release pipeline; no change from 1.1.0.

### 1.1.0

- Post-meal reviews from an app (#453): `reviewsMatch`, the dishes of an order your backend sent that the
  diner can rate, and `reviewsSubmit`, their stars, one review per dish per order (sending again changes
  a rating). A new error code, `review_refused`, with `reviewRefusal` (an open list).
- The diner's nutrition goal (#450): a `dishes` card can carry `goal` (`mode`, the dishes that `fits` it by the restaurant's own figures, and the `unknown` ones it has no figures for), and each `surprise_basket` basket can carry `nutrition` (the meal's figures, each null unless every dish has it) and `goalFit`. All optional; `goal.mode` and `goalFit` are open lists.
- `GET` and `PUT /api/v1/goal` (#450): the goal Tamr keeps for the session's diner across visits, per meal (`mode`, and optional `kcal` and `proteinGrams`); `PUT` with `goal: null` clears it. `canSet` is false for a guest's session or a test key's, and `PUT` then answers the new error code `identity_required`. `ChatRequest.goal` sends the app's own goal with a message: never stored, it wins over the diner's while it's sent.
- The usual and reorder (#451): `usual()` (`GET /api/v1/usual`) answers the signed-in diner's usual, or their last completed order when there is no usual yet (`kind`, an open list), each item by the order's own title with today's `dish` (null once it's off the menu), `onMenu` and `available`. `usual` is null for a guest's session or a diner with no order. A `cart_proposal` card can carry `reorder` (`which`, `placedAt`, and the order's lines it left out in `dropped`, with a `reason`; both open lists). All additive.
- A dish's choices (#452): each `ChoiceOption` gains `extra` (what choosing it adds; null when nothing) and the
  option's own `calories`, `proteinGrams`, `carbsGrams` and `fatGrams` (null where the restaurant gives none).
  `price` is what the dish costs with the option in a pick-one choice, not an add-on. A dish whose options carry
  figures has no figures of its own in `DishSummary`. All additive.
- The `build` card (#452): the waiter builds a dish with choices with the diner, one choice at a time. `DishBuild`
  carries the dish, each choice with its `picked` option ids and `remaining`, `complete`, `total`, the build's
  `nutrition` and `goalFit`. `CardKind` gains `build` (an open list). All additive.
- Allergens per choice option (#706): each `ChoiceOption` gains `allergens`, what the option brings beyond the
  dish's own (empty when nothing). A chosen option's allergens are checked as the dish's, the app's
  `restrictions` included. Additive.
- `nutritionPut` on the Server API client (`PUT /api/v1/catalog/nutrition`, #685): your own per-dish nutrition figures (`calories`, `proteinGrams`, `carbsGrams`, `fatGrams`), by Tamr's `dishId` or your `externalId`, up to 500 rows, all or nothing. A refused call's `data.rows` gives each row's `reason`, an open list. Your figures only fill the gaps the restaurant left in Tamr. On a dish whose options carry
  figures (#452), they fill only the dish's part without choices.
- Treats on the house (#455): a `CartLine` can carry `treat` (`treatId`, `expiresAt`); price that line at
  zero in your checkout. `sdkTreatRedeem` on the Server API client (`POST /api/v1/sdk/treats/{treatId}/redeem`)
  redeems it once the order is placed, idempotent on the treat id. A new error code, `treat_refused`, with
  `treatRefusal` (an open list). All additive.
- What an app hides (#726): `ChatRequest.hide` (`retailSuggestions`, `loyalty`) sent with each message turns
  take-home suggestions and treats off for that turn, and `AppShown` gains `hideReviews`, `hideRetailSuggestions`
  and `hideLoyalty`, the restaurant's own switches, which apply whatever is sent. Additive.
- `order.cancelled` (#743): a webhook for an order your app heard placed that ended unserved (`status`:
  `declined`, `cancelled` or `expired`; `by`: `restaurant`, `diner` or `time`, an open list), once per order.
  `WebhookEventType` gains it. Additive.
- Test orders (#742): a test key's pickup is checked and priced as a real one and written nowhere; the answer
  and `order.placed` carry `test: true` (an `orderId` that starts `test_`), heard only by test webhook endpoints.
  `OrderPlaced.test` is optional. Additive.

### 1.0.0 (not published: 1.1.0 is the first version on npm, and includes it)

The first release (#448), for `/api/v1` 1.0.

- `createClient` for the Client API: `startSession` (a token, a launch code, or a guest's device), the session and device sent with every call, and `onSessionExpired` asked once with the call sent again once. One typed function for every route, and the chat as an async iterator of typed server-sent events.
- `createServerClient` (`@tamr/api/server`) for the Server API, with a secret key. It throws in a browser.
- Generated from the spec, with no runtime dependencies. A value Tamr adds to an open list reads as its fallback, and a new event or card kind reads as `$unknown`.
- `TamrApiError` with the stable `code`, `requestId` and `retryAfter`.
- Node 20+ and every current browser.
