neon-phal-plugin-notifications 0.1.0__tar.gz

neon_phal_plugin_notifications-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+# NEON AI (TM) SOFTWARE, Software Development Kit & Application Development System
+# All trademark and other rights reserved by their respective owners
+# Copyright 2008-2026 Neongecko.com Inc.
+# BSD-3 License
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
+following conditions are met:
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
+disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
+disclaimer in the documentation and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products
+derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

neon_phal_plugin_notifications-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: neon-phal-plugin-notifications
+Version: 0.1.0
+Summary: Notification Manager PHAL plugin for Neon/OVOS: owns notification state, persistence, snooze/dismiss, and emission policy
+Author-email: Mike Gray <mike@oscillatelabs.net>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/NeonGeckoCom/neon-phal-plugin-notifications
+Project-URL: Repository, https://github.com/NeonGeckoCom/neon-phal-plugin-notifications.git
+Project-URL: Issues, https://github.com/NeonGeckoCom/neon-phal-plugin-notifications/issues
+Keywords: ovos,neon,phal,plugin,notifications,voice assistant
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: neon-data-models>=0.0.3a5
+Requires-Dist: ovos-utils~=0.8
+Requires-Dist: ovos-bus-client~=1.5
+Requires-Dist: ovos-plugin-manager~=2.2
+Requires-Dist: json_database~=0.10
+Requires-Dist: pydantic~=2.9
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.0.291; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# neon-phal-plugin-notifications
+
+Notification Manager for Neon/OVOS, packaged as a PHAL plugin. It is the single
+chokepoint for `ovos.notification.api.*` traffic on the hub messagebus: it
+validates producer requests, owns notification state (active / snoozed /
+dismissed / expired), persists that state across restarts, enforces emission
+and dismissal policy, and emits `notify` / `dismiss` / `snoozed` events for
+consumers (the Node app today, other plugins later).
+
+The plugin never renders anything and never talks to MQ. Bus in, bus out.
+Transport lives in `neon-messagebus-mq-connector` and `neon-hana`; rendering
+lives in consumers.
+
+## Requirements
+
+Notification data models come from `neon-data-models`. Until the next release
+they live on the `FEAT_Notifications` branch; install that branch first:
+
+```bash
+pip install git+https://github.com/NeonGeckoCom/neon-data-models@FEAT_Notifications
+pip install neon-phal-plugin-notifications
+```
+
+## Configuration
+
+All keys live under the plugin's PHAL section. Every key is optional.
+
+```yaml
+PHAL:
+  neon-phal-plugin-notifications:
+    store: json                      # persistence adapter; only "json" ships
+    store_path: null                 # override the JSON file path (default:
+                                     # $XDG_DATA_HOME/neon/neon-phal-plugin-notifications/notifications.json)
+    allow_global:                    # skill_ids permitted to use scope=GLOBAL
+      - skill-alerts.neongeckocom
+    allow_non_removable:             # skill_ids permitted to set removable_by_user=false
+      - skill-alerts.neongeckocom
+    rate_limit: 30                   # accepted `set` requests per producer per window
+    rate_window_seconds: 3600
+    consumers_allowed_to_dismiss: [] # empty/absent = every consumer may dismiss
+    consumers_blocked_from_dismiss: []
+    retention_max_age_days: 7        # tombstone window for dismissed/expired entries
+    tick_seconds: 60                 # expiry + retention sweep interval
+```
+
+Policy defaults are asymmetric on purpose: dismissal is open, high-impact
+emission (GLOBAL scope, non-removable) is closed except for seeded first-party
+producers. An unlisted producer that requests either is refused with a reason
+in `.set.response`; nothing is silently downgraded.
+
+## Message API
+
+Every request gets a `.response` reply on the request's own context, so MQ
+routing survives the round trip.
+
+| Consumed | Reply |
+| --- | --- |
+| `ovos.notification.api.set` `{notification}` | `.set.response` `{notification_id, status, reason?}` |
+| `ovos.notification.api.remove` `{notification_id?, skill_id?, dismissed_by?}` | `.remove.response` `{notification_ids, status, reason?}` |
+| `ovos.notification.api.get` `{notification_id}` | `.get.response` `{notification}` |
+| `ovos.notification.api.list` `{skill_id?, state?, since?, node_id?, user_id?}` | `.list.response` `{notifications, states}` |
+| `ovos.notification.api.snooze` `{notification_id, duration}` | `.snooze.response` `{notification_id, status, renotify_at?, reason?}` |
+| `ovos.notification.api.interaction` `{notification_id, action_id, callback_data?}` | none; re-emitted for the producer, then dismissed if the action's `dismiss_on_activate` is true |
+| `ovos.notification.api.sync.request` `{since?}` | `.sync.request.response` `{notifications, states, server_time}` plus one `notify` per entry |
+| `ovos.notification.api.set.controlled` / `.remove.controlled` | deprecated wrappers; reply as `.set.response` / `.remove.response` |
+
+| Emitted | When |
+| --- | --- |
+| `ovos.notification.api.notify` `{notification}` | a `set` is accepted, a snooze elapses, `mycroft.ready`, `sync.request` |
+| `ovos.notification.api.dismiss` `{notification_id, skill_id, scope, target, dismissed_by}` | a notification is removed, dismissed, or expires (`dismissed_by: "expired"`) |
+| `ovos.notification.api.snoozed` `{notification_id, renotify_at, scope, target}` | a snooze is granted |
+
+Behavior notes:
+
+- `set` is an upsert. The same `skill_id` re-sending an existing
+  `notification_id` replaces it in place, resets it to ACTIVE, and re-emits
+  `notify`. A `notification_id` owned by a different `skill_id` is refused.
+- `created_at` is stamped by the manager on first accept and preserved on
+  updates; `updated_at` is bumped on every change (upsert, snooze,
+  re-notify, dismissal, expiry, per-client dismissal) and rides on the wire
+  `Notification`. Every `since` filter (`list`, `sync.request`, and so the
+  HANA REST catch-up) compares against `updated_at`.
+- Retention is a tombstone window, not history: DISMISSED and EXPIRED entries
+  stay for `retention_max_age_days` so a node that was offline learns on
+  catch-up that a notification was dismissed elsewhere, then they are pruned.
+  ACTIVE and SNOOZED entries are never pruned.
+- A missing `session` is filled from `Message.context.session`. A CLIENT-scoped
+  notification with no `target` takes the requester's node identity from the
+  context (`context.node.node_id`, then `context.client_id`, then a non-local
+  `session.session_id`).
+- `remove` needs `notification_id` (the producer is resolved from the stored
+  record; a `skill_id` that disagrees with it is refused) or `skill_id` alone
+  (remove everything that producer owns). Neither is refused. The requester
+  is `dismissed_by`, else `skill_id`, else the context's node/session
+  identity. A requester equal to the producer bypasses `removable_by_user`;
+  anyone else is a consumer subject to `removable_by_user` and the consumer
+  dismiss lists.
+- `dismiss_policy=PER_CLIENT`: a consumer dismissal records that client and
+  leaves the shared state ACTIVE; `list` with `node_id` reports DISMISSED for
+  that client only. `SHARED` dismissals set DISMISSED for everyone.
+- Legacy flat GUI-API payloads (`sender`, `text`, `action`, `type`, `style`)
+  are up-converted with a deprecation log.
+
+## Testing
+
+```bash
+pip install -e .[test]
+pytest tests/
+```

neon_phal_plugin_notifications-0.1.0/README.md

@@ -0,0 +1,109 @@
+# neon-phal-plugin-notifications
+
+Notification Manager for Neon/OVOS, packaged as a PHAL plugin. It is the single
+chokepoint for `ovos.notification.api.*` traffic on the hub messagebus: it
+validates producer requests, owns notification state (active / snoozed /
+dismissed / expired), persists that state across restarts, enforces emission
+and dismissal policy, and emits `notify` / `dismiss` / `snoozed` events for
+consumers (the Node app today, other plugins later).
+
+The plugin never renders anything and never talks to MQ. Bus in, bus out.
+Transport lives in `neon-messagebus-mq-connector` and `neon-hana`; rendering
+lives in consumers.
+
+## Requirements
+
+Notification data models come from `neon-data-models`. Until the next release
+they live on the `FEAT_Notifications` branch; install that branch first:
+
+```bash
+pip install git+https://github.com/NeonGeckoCom/neon-data-models@FEAT_Notifications
+pip install neon-phal-plugin-notifications
+```
+
+## Configuration
+
+All keys live under the plugin's PHAL section. Every key is optional.
+
+```yaml
+PHAL:
+  neon-phal-plugin-notifications:
+    store: json                      # persistence adapter; only "json" ships
+    store_path: null                 # override the JSON file path (default:
+                                     # $XDG_DATA_HOME/neon/neon-phal-plugin-notifications/notifications.json)
+    allow_global:                    # skill_ids permitted to use scope=GLOBAL
+      - skill-alerts.neongeckocom
+    allow_non_removable:             # skill_ids permitted to set removable_by_user=false
+      - skill-alerts.neongeckocom
+    rate_limit: 30                   # accepted `set` requests per producer per window
+    rate_window_seconds: 3600
+    consumers_allowed_to_dismiss: [] # empty/absent = every consumer may dismiss
+    consumers_blocked_from_dismiss: []
+    retention_max_age_days: 7        # tombstone window for dismissed/expired entries
+    tick_seconds: 60                 # expiry + retention sweep interval
+```
+
+Policy defaults are asymmetric on purpose: dismissal is open, high-impact
+emission (GLOBAL scope, non-removable) is closed except for seeded first-party
+producers. An unlisted producer that requests either is refused with a reason
+in `.set.response`; nothing is silently downgraded.
+
+## Message API
+
+Every request gets a `.response` reply on the request's own context, so MQ
+routing survives the round trip.
+
+| Consumed | Reply |
+| --- | --- |
+| `ovos.notification.api.set` `{notification}` | `.set.response` `{notification_id, status, reason?}` |
+| `ovos.notification.api.remove` `{notification_id?, skill_id?, dismissed_by?}` | `.remove.response` `{notification_ids, status, reason?}` |
+| `ovos.notification.api.get` `{notification_id}` | `.get.response` `{notification}` |
+| `ovos.notification.api.list` `{skill_id?, state?, since?, node_id?, user_id?}` | `.list.response` `{notifications, states}` |
+| `ovos.notification.api.snooze` `{notification_id, duration}` | `.snooze.response` `{notification_id, status, renotify_at?, reason?}` |
+| `ovos.notification.api.interaction` `{notification_id, action_id, callback_data?}` | none; re-emitted for the producer, then dismissed if the action's `dismiss_on_activate` is true |
+| `ovos.notification.api.sync.request` `{since?}` | `.sync.request.response` `{notifications, states, server_time}` plus one `notify` per entry |
+| `ovos.notification.api.set.controlled` / `.remove.controlled` | deprecated wrappers; reply as `.set.response` / `.remove.response` |
+
+| Emitted | When |
+| --- | --- |
+| `ovos.notification.api.notify` `{notification}` | a `set` is accepted, a snooze elapses, `mycroft.ready`, `sync.request` |
+| `ovos.notification.api.dismiss` `{notification_id, skill_id, scope, target, dismissed_by}` | a notification is removed, dismissed, or expires (`dismissed_by: "expired"`) |
+| `ovos.notification.api.snoozed` `{notification_id, renotify_at, scope, target}` | a snooze is granted |
+
+Behavior notes:
+
+- `set` is an upsert. The same `skill_id` re-sending an existing
+  `notification_id` replaces it in place, resets it to ACTIVE, and re-emits
+  `notify`. A `notification_id` owned by a different `skill_id` is refused.
+- `created_at` is stamped by the manager on first accept and preserved on
+  updates; `updated_at` is bumped on every change (upsert, snooze,
+  re-notify, dismissal, expiry, per-client dismissal) and rides on the wire
+  `Notification`. Every `since` filter (`list`, `sync.request`, and so the
+  HANA REST catch-up) compares against `updated_at`.
+- Retention is a tombstone window, not history: DISMISSED and EXPIRED entries
+  stay for `retention_max_age_days` so a node that was offline learns on
+  catch-up that a notification was dismissed elsewhere, then they are pruned.
+  ACTIVE and SNOOZED entries are never pruned.
+- A missing `session` is filled from `Message.context.session`. A CLIENT-scoped
+  notification with no `target` takes the requester's node identity from the
+  context (`context.node.node_id`, then `context.client_id`, then a non-local
+  `session.session_id`).
+- `remove` needs `notification_id` (the producer is resolved from the stored
+  record; a `skill_id` that disagrees with it is refused) or `skill_id` alone
+  (remove everything that producer owns). Neither is refused. The requester
+  is `dismissed_by`, else `skill_id`, else the context's node/session
+  identity. A requester equal to the producer bypasses `removable_by_user`;
+  anyone else is a consumer subject to `removable_by_user` and the consumer
+  dismiss lists.
+- `dismiss_policy=PER_CLIENT`: a consumer dismissal records that client and
+  leaves the shared state ACTIVE; `list` with `node_id` reports DISMISSED for
+  that client only. `SHARED` dismissals set DISMISSED for everyone.
+- Legacy flat GUI-API payloads (`sender`, `text`, `action`, `type`, `style`)
+  are up-converted with a deprecation log.
+
+## Testing
+
+```bash
+pip install -e .[test]
+pytest tests/
+```

neon_phal_plugin_notifications-0.1.0/neon_phal_plugin_notifications/__init__.py

@@ -0,0 +1,259 @@
+# NEON AI (TM) SOFTWARE, Software Development Kit & Application Development System
+# All trademark and other rights reserved by their respective owners
+# Copyright 2008-2026 Neongecko.com Inc.
+# BSD-3
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+# 3. Neither the name of the copyright holder nor the names of its
+#    contributors may be used to endorse or promote products derived from this
+#    software without specific prior written permission.
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
+# OR PROFITS;  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE,  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""
+Notification Manager PHAL plugin. Bus in, bus out: this module
+adapts `ovos.notification.api.*` traffic to `NotificationManager`. It never
+renders anything and never talks MQ directly.
+"""
+
+from datetime import timedelta
+from threading import Event
+from typing import Optional
+
+from ovos_bus_client.message import Message
+from ovos_plugin_manager.templates.phal import PHALPlugin
+from ovos_utils.log import LOG
+from pydantic import BaseModel, ValidationError
+
+from neon_data_models.models.api.messagebus.notifications import (
+    NotificationGetData, NotificationGetResponseData,
+    NotificationInteractionData, NotificationListData,
+    NotificationListResponseData, NotificationRemoveData,
+    NotificationRemoveResponseData, NotificationSetData,
+    NotificationSetResponseData, NotificationSnoozeData,
+    NotificationSnoozeResponseData, NotificationSyncRequestData)
+from neon_data_models.models.base.notifications import Notification
+
+from neon_phal_plugin_notifications.identity import is_forwarded
+from neon_phal_plugin_notifications.legacy import (is_legacy_payload,
+                                                   legacy_to_notification,
+                                                   normalize_skill_id)
+from neon_phal_plugin_notifications.manager import (
+    DEFAULT_RETENTION_MAX_AGE_DAYS, NotificationManager)
+from neon_phal_plugin_notifications.policy import (ConsumerDismissPolicy,
+                                                   EmissionPolicy)
+from neon_phal_plugin_notifications.store import (JsonNotificationStore,
+                                                  NotificationStore)
+
+PLUGIN_NAME = "neon-phal-plugin-notifications"
+API = "ovos.notification.api"
+MSG_SET = f"{API}.set"
+MSG_SET_CONTROLLED = f"{API}.set.controlled"
+MSG_REMOVE = f"{API}.remove"
+MSG_REMOVE_CONTROLLED = f"{API}.remove.controlled"
+MSG_GET = f"{API}.get"
+MSG_LIST = f"{API}.list"
+MSG_SNOOZE = f"{API}.snooze"
+MSG_INTERACTION = f"{API}.interaction"
+MSG_SYNC = f"{API}.sync.request"
+MSG_READY = "mycroft.ready"
+RESPONSE_SUFFIX = ".response"
+DEFAULT_STORE = "json"
+DEFAULT_TICK_SECONDS = 60
+
+
+def build_store(config: dict, plugin_name: str = PLUGIN_NAME
+                ) -> NotificationStore:
+    """Select the persistence adapter by the `store` config key."""
+    kind = config.get("store", DEFAULT_STORE)
+    if kind != DEFAULT_STORE:
+        raise ValueError(f"unsupported notification store '{kind}'; only "
+                         f"'{DEFAULT_STORE}' ships in this version")
+    return JsonNotificationStore(path=config.get("store_path"),
+                                 plugin_name=plugin_name)
+
+
+class NotificationManagerPlugin(PHALPlugin):
+    def __init__(self, bus=None, config: Optional[dict] = None,
+                 name: str = PLUGIN_NAME,
+                 store: Optional[NotificationStore] = None):
+        # The base __init__ starts the thread; `run` blocks on `_ready` until
+        # the manager exists
+        self._ready = Event()
+        self._stop_event = Event()
+        super().__init__(bus=bus, name=name, config=config)
+        self.tick_seconds = self.config.get("tick_seconds", DEFAULT_TICK_SECONDS)
+        self.manager = self._build_manager(store or build_store(self.config,
+                                                                name))
+        self.manager.restore()
+        self._register_handlers()
+        self._ready.set()
+
+    def _build_manager(self, store: NotificationStore) -> NotificationManager:
+        max_age = timedelta(days=self.config.get(
+            "retention_max_age_days", DEFAULT_RETENTION_MAX_AGE_DAYS))
+        return NotificationManager(
+            store=store, emit=self._emit_event,
+            emission_policy=EmissionPolicy.from_config(self.config),
+            dismiss_policy=ConsumerDismissPolicy.from_config(self.config),
+            retention_max_age=max_age)
+
+    @property
+    def _handlers(self) -> dict:
+        return {
+            MSG_SET: self.handle_set,
+            MSG_SET_CONTROLLED: self.handle_set_controlled,
+            MSG_REMOVE: self.handle_remove,
+            MSG_REMOVE_CONTROLLED: self.handle_remove_controlled,
+            MSG_GET: self.handle_get,
+            MSG_LIST: self.handle_list,
+            MSG_SNOOZE: self.handle_snooze,
+            MSG_INTERACTION: self.handle_interaction,
+            MSG_SYNC: self.handle_sync_request,
+            MSG_READY: self.handle_ready,
+        }
+
+    def _register_handlers(self) -> None:
+        for msg_type, handler in self._handlers.items():
+            self.bus.on(msg_type, handler)
+
+    def run(self):
+        self._ready.wait()
+        while not self._stop_event.wait(self.tick_seconds):
+            self.manager.tick()
+
+    def shutdown(self):
+        self._stop_event.set()
+        for msg_type, handler in self._handlers.items():
+            self.bus.remove(msg_type, handler)
+        self.manager.shutdown()
+        super().shutdown()
+
+    # ---- producer handlers --------------------------------------------------
+    def handle_set(self, message: Message):
+        self._handle_set(message, controlled=False)
+
+    def handle_set_controlled(self, message: Message):
+        LOG.warning("%s is deprecated; send %s with `removable_by_user: "
+                    "false`", MSG_SET_CONTROLLED, MSG_SET)
+        self._handle_set(message, controlled=True)
+
+    def _handle_set(self, message: Message, controlled: bool) -> None:
+        try:
+            notification = self._parse_notification(message, controlled)
+        except (ValidationError, ValueError, KeyError) as e:
+            self._reply(message, MSG_SET, NotificationSetResponseData(
+                notification_id=_requested_id(message.data), status="refused",
+                reason=f"invalid notification payload: {e}"))
+            return
+        self._reply(message, MSG_SET,
+                    self.manager.set(notification, message.context))
+
+    @staticmethod
+    def _parse_notification(message: Message, controlled: bool) -> Notification:
+        data = dict(message.data)
+        if is_legacy_payload(data):
+            return legacy_to_notification(data, removable_by_user=not controlled)
+        payload = normalize_skill_id(dict(data.get("notification") or {}))
+        if "session" not in payload and message.context.get("session"):
+            payload["session"] = message.context["session"]
+        if controlled:
+            payload["removable_by_user"] = False
+        return NotificationSetData(notification=payload).notification
+
+    def handle_remove(self, message: Message):
+        try:
+            data = NotificationRemoveData(**message.data)
+        except ValidationError as e:
+            self._reply(message, MSG_REMOVE, NotificationRemoveResponseData(
+                notification_ids=[], status="refused",
+                reason=f"invalid remove payload: {e}"))
+            return
+        self._reply(message, MSG_REMOVE,
+                    self.manager.remove(data, message.context))
+
+    def handle_remove_controlled(self, message: Message):
+        LOG.warning("%s is deprecated; send %s", MSG_REMOVE_CONTROLLED,
+                    MSG_REMOVE)
+        self.handle_remove(message)
+
+    def handle_get(self, message: Message):
+        try:
+            data = NotificationGetData(**message.data)
+        except ValidationError as e:
+            LOG.error("invalid get payload: %s", e)
+            self._reply(message, MSG_GET, NotificationGetResponseData())
+            return
+        self._reply(message, MSG_GET, self.manager.get(data.notification_id))
+
+    def handle_list(self, message: Message):
+        try:
+            data = NotificationListData(**message.data)
+        except ValidationError as e:
+            LOG.error("invalid list payload: %s", e)
+            self._reply(message, MSG_LIST, NotificationListResponseData(
+                notifications=[], states={}))
+            return
+        self._reply(message, MSG_LIST, self.manager.list(data))
+
+    def handle_snooze(self, message: Message):
+        try:
+            data = NotificationSnoozeData(**message.data)
+        except ValidationError as e:
+            self._reply(message, MSG_SNOOZE, NotificationSnoozeResponseData(
+                notification_id=_requested_id(message.data), status="refused",
+                reason=f"invalid snooze payload: {e}"))
+            return
+        self._reply(message, MSG_SNOOZE,
+                    self.manager.snooze(data, message.context))
+
+    # ---- consumer handlers --------------------------------------------------
+    def handle_interaction(self, message: Message):
+        if is_forwarded(message.context):
+            return
+        try:
+            data = NotificationInteractionData(**message.data)
+        except ValidationError as e:
+            LOG.error("invalid interaction payload: %s", e)
+            return
+        self.manager.interact(data, message.context)
+
+    def handle_sync_request(self, message: Message):
+        try:
+            data = NotificationSyncRequestData(**message.data)
+        except ValidationError as e:
+            LOG.error("invalid sync payload: %s", e)
+            data = NotificationSyncRequestData()
+        self._reply(message, MSG_SYNC, self.manager.sync(data, message.context))
+
+    def handle_ready(self, message: Message):
+        count = self.manager.announce_active()
+        LOG.info("re-emitted notify for %s active notifications", count)
+
+    # ---- bus plumbing -------------------------------------------------------
+    def _reply(self, message: Message, request_type: str,
+               data: BaseModel) -> None:
+        self.bus.emit(message.reply(request_type + RESPONSE_SUFFIX,
+                                    data.model_dump()))
+
+    def _emit_event(self, msg_type: str, data: BaseModel, context: dict) -> None:
+        self.bus.emit(Message(msg_type, data.model_dump(), dict(context)))
+
+
+def _requested_id(data: dict) -> str:
+    nested = data.get("notification") or {}
+    return str(nested.get("notification_id") or data.get("notification_id")
+               or "")

neon_phal_plugin_notifications-0.1.0/neon_phal_plugin_notifications/authorization.py

@@ -0,0 +1,93 @@
+# NEON AI (TM) SOFTWARE, Software Development Kit & Application Development System
+# All trademark and other rights reserved by their respective owners
+# Copyright 2008-2026 Neongecko.com Inc.
+# BSD-3
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+# 3. Neither the name of the copyright holder nor the names of its
+#    contributors may be used to endorse or promote products derived from this
+#    software without specific prior written permission.
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
+# OR PROFITS;  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE,  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""
+Authorization decisions for consumer remove/dismiss requests.
+"""
+
+from typing import Optional, Tuple
+
+from neon_data_models.enum import DismissPolicy
+from neon_data_models.models.api.messagebus.notifications import \
+    NotificationRemoveData
+
+from neon_phal_plugin_notifications import identity
+from neon_phal_plugin_notifications.policy import ConsumerDismissPolicy
+from neon_phal_plugin_notifications.store import StoredNotification
+
+UNKNOWN_CONSUMER = "unknown"
+
+# (refusal_reason, dismissed_by, per_client_id); reason None means allowed
+RemovalVerdict = Tuple[Optional[str], Optional[str], Optional[str]]
+
+
+def requester_identity(data: NotificationRemoveData,
+                       context: dict) -> Optional[str]:
+    """
+    Who is asking: `data.dismissed_by` (HANA REST dismiss), else the payload
+    `skill_id` (a producer removing its own), else the context's consumer.
+    """
+    return (data.dismissed_by or data.skill_id
+            or identity.consumer_id(context))
+
+
+def per_client_id(record: StoredNotification,
+                  consumer: Optional[str]) -> Optional[str]:
+    """Client to record a dismissal against, for PER_CLIENT notifications."""
+    if record.notification.dismiss_policy == DismissPolicy.PER_CLIENT:
+        return consumer
+    return None
+
+
+def authorize_removal(record: StoredNotification, data: NotificationRemoveData,
+                      context: dict, policy: ConsumerDismissPolicy
+                      ) -> RemovalVerdict:
+    """A requester identified as the producer bypasses `removable_by_user`."""
+    consumer = requester_identity(data, context)
+    if consumer == record.skill_id:
+        return None, record.skill_id, None
+    allowed, reason = policy.check(consumer)
+    if not allowed:
+        return reason, None, None
+    if not record.notification.removable_by_user:
+        return (f"notification '{record.notification_id}' is only removable "
+                f"by its producer '{record.skill_id}'"), None, None
+    client_id = per_client_id(record, consumer)
+    if (record.notification.dismiss_policy == DismissPolicy.PER_CLIENT
+            and client_id is None):
+        return ("PER_CLIENT dismissal requires a client identity in the "
+                "message context"), None, None
+    return None, consumer or UNKNOWN_CONSUMER, client_id
+
+
+def snooze_refusal(record: Optional[StoredNotification],
+                   duration: int) -> Optional[str]:
+    if record is None:
+        return "unknown notification"
+    if not record.is_live():
+        return f"notification is {record.state.value}"
+    if duration <= 0:
+        return "duration must be a positive number of seconds"
+    return None