Notifications and push

Show app.notify banners, toasts, alerts and OS notifications; register a push token and hand incoming pushes to the SDK.

MaterialApp(
  builder: (context, child) => KletsoNotificationHost(
    client: Kletso.instance,
    bannerDuration: const Duration(seconds: 8),
    toastDuration: const Duration(seconds: 4),
    maxVisible: 2,
    onTap: (n) => analytics.log('kletso_notification_tap', n.id),
    child: child!,
  ),
)

Mount it once above the navigator. It listens to client.notifications and renders by channel:

Channel	Rendering	Tap
`banner`	Card at the top, swipe to dismiss, auto-dismisses after `ttlSeconds` or `bannerDuration`	Runs the target
`toast`	Pill at the bottom, short	Runs the target
`alert`	Dialog with the title, body, optional inline surface and a button	Runs the target
`system`	Handed to your `onSystemNotification`; falls back to a banner if you return `false` or set none	Your plugin’s tap → `openNotification`
`silent`	No UI; the target runs immediately	n/a

The target is openChat (switch to the notification’s conversation and open the chat) plus an optional action: local (your handler, origin: notification), url, or agent (a value sent to the model after the chat opens).

Outcomes are published on client.ui.notificationResults (shown, system, bannerFallback, silent, tapped).

OS tray for `system`

Kletso.instance.onSystemNotification = (n) async {
  final ok = await localNotifications.show(n.id.hashCode, n.title, n.payload.body, details,
      payload: n.id);
  return ok;                          // false → SDK shows a banner instead
};
// when the user taps the OS notification:
Kletso.instance.ui.openNotification(n);

The SDK ships no notifications plugin on purpose; use the one you already have.

Push when the app is in the background

Get a token from your push SDK and register it:
```
await Kletso.instance.registerPushToken(
  KletsoPushToken(platform: KletsoPushPlatform.fcm, token: fcmToken));
```
Platforms: fcm, apns, webPush. Only FCM is delivered by the runtime today; see Roadmap.
Configure the FCM service account under Triggers → Push delivery in the dashboard (stored as a secret).
Feed every incoming push to the SDK:
```
FirebaseMessaging.onMessage.listen((m) => Kletso.instance.handlePushPayload(m.data));
```
handlePushPayload reads the kletso field (a kletso.events/v1 envelope of type app.notify), returns true for a new notification and false for one already shown live. Deduplication is on notificationId, so double delivery renders once.

Pushes for channels other than system are data-only: the app renders the banner or toast itself when it is in the foreground. For system the push includes a notification block, so the OS shows it even when the app is killed.

unregisterPushToken() removes the token, for example on logout.

Notifications and push

The host widget

OS tray for system

Push when the app is in the background

OS tray for `system`