---
title: Messages kit
description: What the page said, such as Saved or an error, as messages status and as message.shown events.
---

# Messages kit

After a save or a page change, apps show messages: "Saved", or what went
wrong. People read them on screen; the messages kit hands them to agents in
two ways, fed by one adapter function:

- `messages status` lists them, for an agent that asks. A bare `status` (and
  `sutram_status`) includes it, with how many there are and the latest.
- Each message is emitted as a `message.shown` event, for an agent that reads
  `events recent` or waits for one with `events wait message.shown`.

| Command | Does | Annotations |
|---|---|---|
| `messages status` | The messages this page has shown, oldest first | read-only, `untrustedContent` |

When a command starts Sutram again, the note agents get says to look again
with `status` once the page is ready, which includes the messages.

## The adapter

```js
import { messages } from "@d34dman/sutram/messages";

const shown = [];   // your app adds to it when it shows a message
messages({
  // The messages shown since the page loaded, oldest first.
  messages: () => shown,
  // Optional: say when new messages may have come without a new page.
  watch: (changed) => { app.onMessage = changed; return () => { app.onMessage = null; }; },
});
```

| Adapter key | Required | What it is |
|---|---|---|
| `messages()` | yes | `[{ type, text }]`, where `type` is `status`, `warning` or `error`. It may return a promise. |
| `watch(changed)` | no | Calls `changed()` when new messages may have come without a page load, such as after an AJAX request. May return a function that stops watching. |

The kit asks `messages()` when the command runs, once when the kit is set
up, and after each `changed()`. It emits `message.shown` for the messages
there are at the start, and after each `changed()` for those that are new:
the ones after the list it saw last, or all of them when the list starts
afresh (after a route change, say).

```text
> messages status
1 message; the latest (status): Article Hello has been updated.
TYPE    TEXT
status  Article Hello has been updated.
```

Give the text as people read it, without HTML.

## Without a bundler

Load `dist/messages.js` after `dist/sutram.js` and call
`Sutram.kits.messages()`. In Drupal, `drupal/sutram` ships it as the library
`sutram/messages`, and `sutram_demo_messages` is the adapter. See
[Drupal](../drupal.md).