three.ws Notifications

Permanently delete a single notification from the inbox by its `id` (from list_notifications). Unlike mark_read, which only marks it read, this REMOVES the notification for good — the action is irreversible. Only a notification the caller owns can be deleted. Returns `{ ok: true, id, deleted: true }` on success, or a not_found error if the id does not exist for this account (e.g. it was already deleted). Prefer mark_read for normal triage; use this only to discard a notification entirely.

Read the account's notification delivery preferences — the resolved channel matrix the platform uses to decide how each kind of event reaches the owner. Returns `categories` (the catalog of user-facing groups: sales, purchases, social, irl, alerts, account — each with a label and description), `channels` (the deliverable channels: in_app, push, email, telegram), `prefs` (the effective per-category → per-channel on/off matrix with sparse user overrides already merged onto defaults, plus the linked `telegram_chat_id` if any), and `push` (how many web-push devices are registered). Read this before calling set_preferences so you patch from the real current state. Read-only.

Read the authenticated agent's notification inbox — the inbound-event feed the platform delivers to the account: market/pump alerts, sales & earnings, purchase receipts, social mentions, IRL interactions, and account/security notices. Returns the most recent notifications (newest first), each with its `id`, `type`, the event `payload`, a `read` boolean and `read_at` timestamp (null ⇒ unread), and `created_at`; plus `unread_count`, the total number of unread items in the inbox. Pass `type` to return only one notification type (e.g. "pump_alert", "skill_purchased", "security_alert"), and `limit` (1–50, default 20) to cap how many rows come back. Read-only — use it to surface alerts without polling, then mark_read / delete_notification to manage them.

Mark notifications as read in the inbox. Pass `id` to mark a single notification read, or `all: true` to mark every unread notification read at once (exactly one of the two is required). Marking read only updates the read timestamp — it does not delete anything, and re-running with the same arguments has no further effect (idempotent). When `id` is given, returns the notification id and its `read_at`; when `all` is given, returns `marked_read`, the number of notifications newly marked read. To remove a notification entirely use delete_notification instead.

Register a Web Push device so the account receives push notifications on it. Pass the browser `subscription` object exactly as `pushManager.subscribe().toJSON()` produces it — { endpoint, keys: { p256dh, auth } }. Push endpoints are globally unique: re-registering the same device upserts (the latest owner wins) and is a no-op, so this is idempotent. Whether a given notification category actually delivers over push is still governed by set_preferences. Returns `{ ok: true }` on success. Use unregister_push_device to remove a device.

Update the account's notification delivery preferences with a sparse patch. `categories` maps a category key (sales, purchases, social, irl, alerts, account) to a channel map turning each channel on/off (in_app, push, email, telegram) — e.g. { "alerts": { "push": false }, "social": { "email": true } }. Only the category/channel pairs you pass change; unknown keys are dropped server-side and untouched pairs keep their current value (which falls back to the platform default). Pass `telegram_chat_id` (a numeric Telegram chat id, or "" to unlink) to control where the telegram channel delivers. Provide at least one of `categories` or `telegram_chat_id`. WRITE but idempotent — re-applying the same values is a no-op. Returns the full resolved preference matrix after the update. Read it first with get_preferences.

Remove a Web Push device so the account stops receiving push notifications on it. Identify the device by its push `endpoint` URL (preferred) or by passing the full `subscription` object — at least one is required. Destructive: it tears down the device registration (reverse it by calling register_push_device again). Idempotent: removing an endpoint that is not registered still returns `{ ok: true }`. This affects only push delivery to that device; in_app, email, and telegram preferences are unchanged.