flet-notifications 0.1.0__tar.gz

flet_notifications-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Onyeka Nwokike
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flet_notifications-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: flet-notifications
+Version: 0.1.0
+Summary: Cross-platform local notifications for Flet apps (Android, iOS, macOS, Windows, Linux, Web).
+Author-email: Onyeka Nwokike <nwokikeonyeka@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Nwokike/flet-notifications
+Project-URL: Repository, https://github.com/Nwokike/flet-notifications
+Project-URL: Issues, https://github.com/Nwokike/flet-notifications/issues
+Keywords: flet,notifications,desktop,android,ios,cross-platform
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flet>=1.0.0
+Dynamic: license-file
+
+# flet-notifications
+
+[![pypi](https://img.shields.io/pypi/v/flet-notifications.svg)](https://pypi.python.org/pypi/flet-notifications)
+[![python](https://img.shields.io/badge/python-%3E%3D3.10-%2334D058)](https://pypi.org/project/flet-notifications)
+[![license](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/Nwokike/flet-notifications/blob/main/LICENSE)
+
+Cross-platform local notifications for [Flet](https://flet.dev) apps.
+
+A 1:1 wrapping of the official [flutter_local_notifications](https://pub.dev/packages/flutter_local_notifications) Flutter plugin, in the same architecture as [flet-ads](https://pypi.org/project/flet-ads/). One `uv add flet-notifications` covers Android, iOS, macOS, Windows, Linux and Web — no Python dependencies beyond `flet`.
+
+## Test it without an account
+
+Every release builds the example app for every platform. Sideload any of them and every button is live:
+
+| Variant | Download | Notes |
+| :--- | :---: | :--- |
+| 📱 **ARM64** (most phones/TVs) | [**app-arm64-v8a-release.apk**](https://github.com/Nwokike/flet-notifications/releases/latest/download/app-arm64-v8a-release.apk) | Modern 64-bit Android devices — grab this one unless you know otherwise |
+| 📱 **ARMv7** (older phones/TV boxes) | [**app-armeabi-v7a-release.apk**](https://github.com/Nwokike/flet-notifications/releases/latest/download/app-armeabi-v7a-release.apk) | Legacy 32-bit Android devices |
+| 💻 **x86_64** (emulators/ChromeOS) | [**app-x86_64-release.apk**](https://github.com/Nwokike/flet-notifications/releases/latest/download/app-x86_64-release.apk) | Android emulators & Chromebooks |
+| 🖥️ **Windows** | [**flet-notifications-example-windows.zip**](https://github.com/Nwokike/flet-notifications/releases/latest/download/flet-notifications-example-windows.zip) | Portable zip |
+| 🍎 **macOS** | [**flet-notifications-example-macos.dmg**](https://github.com/Nwokike/flet-notifications/releases/latest/download/flet-notifications-example-macos.dmg) | Disk image |
+| 🐧 **Linux** | [**tar.gz**](https://github.com/Nwokike/flet-notifications/releases/latest/download/flet-notifications-example-linux-x86_64.tar.gz) · [**deb**](https://github.com/Nwokike/flet-notifications/releases/latest/download/flet-notifications-example_amd64.deb) · [**rpm**](https://github.com/Nwokike/flet-notifications/releases/latest/download/flet-notifications-example_x86_64.rpm) | Bundle or packages |
+| 🌐 **Web** | [**flet-notifications-example-web.tar.gz**](https://github.com/Nwokike/flet-notifications/releases/latest/download/flet-notifications-example-web.tar.gz) | Static bundle |
+
+Plain `flet run` launches the prebuilt client without the extension's Dart half — notifications need a built app (an artifact above, or `flet build <platform>`).
+
+## Platform Support
+
+| Platform | Show | Schedule | Actions & callbacks | Channels | Progress | Notes |
+|----------|:----:|:--------:|:-------------------:|:--------:|:--------:|-------|
+| iOS      |  ✅  |    ✅    |         ✅          |    —     |    —     | 13+; attachments, interruption levels |
+| Android  |  ✅  |    ✅    |         ✅          |    ✅    |    ✅    | 7.0+ (API 24); Android TV works |
+| macOS    |  ✅  |    ✅    |         ✅          |    —     |    —     | 10.15+ |
+| Windows  |  ✅  | one-shot |         ✅          |    —     |    ✅    | 10+; `cancel`/queries need MSIX identity |
+| Linux    |  ✅  |    —     |         ✅          |    —     |    —     | D-Bus server; capabilities vary |
+| Web      |  ✅  |    —     |   Chrome/Edge only  |    —     |    —     | Notifications API; gesture-gated permissions |
+
+## Usage
+
+```bash
+uv add flet-notifications
+```
+
+```python
+import flet as ft
+from flet_notifications import LocalNotifications
+
+def main(page: ft.Page):
+    notifications = LocalNotifications()
+
+    async def on_tap(e):
+        print("tapped:", e.payload)
+
+    notifications.on_tap = on_tap
+
+    if await notifications.request_permissions():
+        await notifications.show(id=1, title="Hello", body="Hello!")
+
+ft.run(main)
+```
+
+## Controls
+
+| Control | Base | Purpose |
+|---|---|---|
+| `LocalNotifications` | `ft.Service` | Show/schedule/cancel, permissions, probes, channels; construct once, it registers itself |
+
+### Event handlers
+
+```python
+notifications.on_tap = on_tap          # typed: NotificationEvent
+notifications.on_action = on_action    # typed: e.action_id, e.input, e.data
+notifications.on_dismissed = handler   # typed
+```
+
+Typed handlers must use `ft.EventHandler[NotificationEvent]`, **not** `ft.ControlEventHandler[NotificationEvent]` — `ControlEventHandler[X]` double-wraps `X` in `Event[...]`, so `e.payload` raises `AttributeError`. `NotificationEvent` carries `id`, `action_id`, `payload`, `input`, `data` and `response_type`.
+
+Taps that arrive while the app wasn't running are replayed on the next start (Android background taps, iOS/macOS cold-start launches).
+
+### Configuration
+
+Scheduling on Android needs permissions in the app's `pyproject.toml`:
+
+```toml
+[tool.flet.android.permission]
+RECEIVE_BOOT_COMPLETED = true   # restore alarms after reboot
+SCHEDULE_EXACT_ALARM = true     # exact schedule modes
+```
+
+The scheduled-notification receivers are `<application>` children, which `[tool.flet.android.*]` cannot declare — the `flet-notifications-patch` console script injects them (plus the core-library-desugaring Gradle flags the plugin needs), idempotently:
+
+```bash
+uv run flet build apk --yes --project myapp --org com.example -v
+uv run flet-notifications-patch --project-root build/flutter
+cd build/flutter/android && ./gradlew assembleRelease -Psplit-per-abi=true
+```
+
+## Configuration reference
+
+**Types:** `NotificationAction`/`NotificationActionInput` (buttons, inline reply) · `BigTextStyle`/`BigPictureStyle`/`InboxStyle`/`MessagingStyle` (+ `Person`, `Message`, `AndroidIcon`) · `NotificationChannel` (importance, sound, vibration, badge, DND, lights) · `NotificationOptions` with `AndroidOptions`/`DarwinOptions`/`LinuxOptions`/`WindowsOptions`/`WebOptions` (the full per-platform detail surface) · enums `RepeatInterval`, `DateTimeComponents`, `AndroidScheduleMode`, `Importance`, `GroupAlertBehavior`, `InterruptionLevel`.
+
+**Calls:** `show` · `schedule` · `periodically_show` · `cancel`/`cancel_all`/`cancel_pending` · `request_permissions` · `are_notifications_enabled` · `can_schedule_exact_notifications`/`request_exact_alarm_permission` · `request_full_screen_intent_permission` · `has`/`request_notification_policy_access` · `open_app_notification_settings` · `get_pending_notifications`/`get_active_notifications`/`get_notification_app_launch_details` · `create`/`delete`/`get_notification_channels` (+ groups) · `start`/`stop_foreground_service`.
+
+**Errors:** `NotificationError` with a stable `code` — `unsupported_platform`, `init_failed`, `show_failed`, `schedule_failed`, `invalid_action`, `invalid_schedule`, `invalid_style`, `invalid_channel`, `invalid_option`, `invalid_service_id`, `channel_failed`, `foreground_service_failed`, `query_failed`, `permission_failed`, `unknown_method`.
+
+## Limitations
+
+- Linux/Web have no OS scheduler; Windows schedules one-shot only.
+- Android channel sound/vibration are immutable after creation; aggressive OEM skins may drop alarms after force-stop; Samsung caps ~500 alarms.
+- Interruptions beyond `passive` on Apple need Xcode capabilities.
+- Not wrapped (upstream niche): HTML-format style flags, `MediaStyle`, action `semanticAction`/`invisible`/`contextual`, CarPlay, message data MIME/URI, Linux custom hints.
+- iOS IPAs need Apple signing and are built owner-side; CI builds every other platform.
+
+## Example
+
+`examples/flet_notifications_example` — every API on one screen with a timestamped event log, built for Windows, macOS, Linux, Android and Web on every release.
+
+## License
+
+MIT

flet_notifications-0.1.0/README.md

@@ -0,0 +1,120 @@
+# flet-notifications
+
+[![pypi](https://img.shields.io/pypi/v/flet-notifications.svg)](https://pypi.python.org/pypi/flet-notifications)
+[![python](https://img.shields.io/badge/python-%3E%3D3.10-%2334D058)](https://pypi.org/project/flet-notifications)
+[![license](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/Nwokike/flet-notifications/blob/main/LICENSE)
+
+Cross-platform local notifications for [Flet](https://flet.dev) apps.
+
+A 1:1 wrapping of the official [flutter_local_notifications](https://pub.dev/packages/flutter_local_notifications) Flutter plugin, in the same architecture as [flet-ads](https://pypi.org/project/flet-ads/). One `uv add flet-notifications` covers Android, iOS, macOS, Windows, Linux and Web — no Python dependencies beyond `flet`.
+
+## Test it without an account
+
+Every release builds the example app for every platform. Sideload any of them and every button is live:
+
+| Variant | Download | Notes |
+| :--- | :---: | :--- |
+| 📱 **ARM64** (most phones/TVs) | [**app-arm64-v8a-release.apk**](https://github.com/Nwokike/flet-notifications/releases/latest/download/app-arm64-v8a-release.apk) | Modern 64-bit Android devices — grab this one unless you know otherwise |
+| 📱 **ARMv7** (older phones/TV boxes) | [**app-armeabi-v7a-release.apk**](https://github.com/Nwokike/flet-notifications/releases/latest/download/app-armeabi-v7a-release.apk) | Legacy 32-bit Android devices |
+| 💻 **x86_64** (emulators/ChromeOS) | [**app-x86_64-release.apk**](https://github.com/Nwokike/flet-notifications/releases/latest/download/app-x86_64-release.apk) | Android emulators & Chromebooks |
+| 🖥️ **Windows** | [**flet-notifications-example-windows.zip**](https://github.com/Nwokike/flet-notifications/releases/latest/download/flet-notifications-example-windows.zip) | Portable zip |
+| 🍎 **macOS** | [**flet-notifications-example-macos.dmg**](https://github.com/Nwokike/flet-notifications/releases/latest/download/flet-notifications-example-macos.dmg) | Disk image |
+| 🐧 **Linux** | [**tar.gz**](https://github.com/Nwokike/flet-notifications/releases/latest/download/flet-notifications-example-linux-x86_64.tar.gz) · [**deb**](https://github.com/Nwokike/flet-notifications/releases/latest/download/flet-notifications-example_amd64.deb) · [**rpm**](https://github.com/Nwokike/flet-notifications/releases/latest/download/flet-notifications-example_x86_64.rpm) | Bundle or packages |
+| 🌐 **Web** | [**flet-notifications-example-web.tar.gz**](https://github.com/Nwokike/flet-notifications/releases/latest/download/flet-notifications-example-web.tar.gz) | Static bundle |
+
+Plain `flet run` launches the prebuilt client without the extension's Dart half — notifications need a built app (an artifact above, or `flet build <platform>`).
+
+## Platform Support
+
+| Platform | Show | Schedule | Actions & callbacks | Channels | Progress | Notes |
+|----------|:----:|:--------:|:-------------------:|:--------:|:--------:|-------|
+| iOS      |  ✅  |    ✅    |         ✅          |    —     |    —     | 13+; attachments, interruption levels |
+| Android  |  ✅  |    ✅    |         ✅          |    ✅    |    ✅    | 7.0+ (API 24); Android TV works |
+| macOS    |  ✅  |    ✅    |         ✅          |    —     |    —     | 10.15+ |
+| Windows  |  ✅  | one-shot |         ✅          |    —     |    ✅    | 10+; `cancel`/queries need MSIX identity |
+| Linux    |  ✅  |    —     |         ✅          |    —     |    —     | D-Bus server; capabilities vary |
+| Web      |  ✅  |    —     |   Chrome/Edge only  |    —     |    —     | Notifications API; gesture-gated permissions |
+
+## Usage
+
+```bash
+uv add flet-notifications
+```
+
+```python
+import flet as ft
+from flet_notifications import LocalNotifications
+
+def main(page: ft.Page):
+    notifications = LocalNotifications()
+
+    async def on_tap(e):
+        print("tapped:", e.payload)
+
+    notifications.on_tap = on_tap
+
+    if await notifications.request_permissions():
+        await notifications.show(id=1, title="Hello", body="Hello!")
+
+ft.run(main)
+```
+
+## Controls
+
+| Control | Base | Purpose |
+|---|---|---|
+| `LocalNotifications` | `ft.Service` | Show/schedule/cancel, permissions, probes, channels; construct once, it registers itself |
+
+### Event handlers
+
+```python
+notifications.on_tap = on_tap          # typed: NotificationEvent
+notifications.on_action = on_action    # typed: e.action_id, e.input, e.data
+notifications.on_dismissed = handler   # typed
+```
+
+Typed handlers must use `ft.EventHandler[NotificationEvent]`, **not** `ft.ControlEventHandler[NotificationEvent]` — `ControlEventHandler[X]` double-wraps `X` in `Event[...]`, so `e.payload` raises `AttributeError`. `NotificationEvent` carries `id`, `action_id`, `payload`, `input`, `data` and `response_type`.
+
+Taps that arrive while the app wasn't running are replayed on the next start (Android background taps, iOS/macOS cold-start launches).
+
+### Configuration
+
+Scheduling on Android needs permissions in the app's `pyproject.toml`:
+
+```toml
+[tool.flet.android.permission]
+RECEIVE_BOOT_COMPLETED = true   # restore alarms after reboot
+SCHEDULE_EXACT_ALARM = true     # exact schedule modes
+```
+
+The scheduled-notification receivers are `<application>` children, which `[tool.flet.android.*]` cannot declare — the `flet-notifications-patch` console script injects them (plus the core-library-desugaring Gradle flags the plugin needs), idempotently:
+
+```bash
+uv run flet build apk --yes --project myapp --org com.example -v
+uv run flet-notifications-patch --project-root build/flutter
+cd build/flutter/android && ./gradlew assembleRelease -Psplit-per-abi=true
+```
+
+## Configuration reference
+
+**Types:** `NotificationAction`/`NotificationActionInput` (buttons, inline reply) · `BigTextStyle`/`BigPictureStyle`/`InboxStyle`/`MessagingStyle` (+ `Person`, `Message`, `AndroidIcon`) · `NotificationChannel` (importance, sound, vibration, badge, DND, lights) · `NotificationOptions` with `AndroidOptions`/`DarwinOptions`/`LinuxOptions`/`WindowsOptions`/`WebOptions` (the full per-platform detail surface) · enums `RepeatInterval`, `DateTimeComponents`, `AndroidScheduleMode`, `Importance`, `GroupAlertBehavior`, `InterruptionLevel`.
+
+**Calls:** `show` · `schedule` · `periodically_show` · `cancel`/`cancel_all`/`cancel_pending` · `request_permissions` · `are_notifications_enabled` · `can_schedule_exact_notifications`/`request_exact_alarm_permission` · `request_full_screen_intent_permission` · `has`/`request_notification_policy_access` · `open_app_notification_settings` · `get_pending_notifications`/`get_active_notifications`/`get_notification_app_launch_details` · `create`/`delete`/`get_notification_channels` (+ groups) · `start`/`stop_foreground_service`.
+
+**Errors:** `NotificationError` with a stable `code` — `unsupported_platform`, `init_failed`, `show_failed`, `schedule_failed`, `invalid_action`, `invalid_schedule`, `invalid_style`, `invalid_channel`, `invalid_option`, `invalid_service_id`, `channel_failed`, `foreground_service_failed`, `query_failed`, `permission_failed`, `unknown_method`.
+
+## Limitations
+
+- Linux/Web have no OS scheduler; Windows schedules one-shot only.
+- Android channel sound/vibration are immutable after creation; aggressive OEM skins may drop alarms after force-stop; Samsung caps ~500 alarms.
+- Interruptions beyond `passive` on Apple need Xcode capabilities.
+- Not wrapped (upstream niche): HTML-format style flags, `MediaStyle`, action `semanticAction`/`invisible`/`contextual`, CarPlay, message data MIME/URI, Linux custom hints.
+- iOS IPAs need Apple signing and are built owner-side; CI builds every other platform.
+
+## Example
+
+`examples/flet_notifications_example` — every API on one screen with a timestamped event log, built for Windows, macOS, Linux, Android and Web on every release.
+
+## License
+
+MIT

flet_notifications-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "flet-notifications"
+version = "0.1.0"
+description = "Cross-platform local notifications for Flet apps (Android, iOS, macOS, Windows, Linux, Web)."
+readme = "README.md"
+authors = [
+    { name = "Onyeka Nwokike", email = "nwokikeonyeka@gmail.com" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["flet", "notifications", "desktop", "android", "ios", "cross-platform"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Intended Audience :: Developers",
+]
+dependencies = [
+    "flet>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Nwokike/flet-notifications"
+Repository = "https://github.com/Nwokike/flet-notifications"
+Issues = "https://github.com/Nwokike/flet-notifications/issues"
+
+[project.scripts]
+flet-notifications-patch = "flet_notifications.patcher:main"
+
+[tool.setuptools.package-data]
+"flutter.flet_notifications" = ["pubspec.yaml", "lib/**"]
+
+[tool.setuptools]
+license-files = ["LICENSE"]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff.lint]
+# Match the flet core source style: Optional[...] and quoted forward
+# references in control/event annotations.
+ignore = ["UP045", "UP037"]

flet_notifications-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

flet_notifications-0.1.0/src/flet_notifications/__init__.py

@@ -0,0 +1,91 @@
+"""flet-notifications: cross-platform local notifications for Flet apps.
+
+Wraps the battle-tested ``flutter_local_notifications`` Flutter plugin and
+exposes it as a native Flet service (``ft.Service``), following the same
+extension architecture as ``flet-ads`` / ``flet-yandex-ads``.
+"""
+
+from flet_notifications.actions import NotificationAction, NotificationActionInput
+from flet_notifications.base import (
+    NotificationError,
+    NotificationErrorCode,
+    NotificationEvent,
+    ResponseType,
+)
+from flet_notifications.channels import NotificationChannel
+from flet_notifications.events import (
+    ActiveNotification,
+    LaunchDetails,
+    PendingNotification,
+)
+from flet_notifications.local_notifications import LocalNotifications
+from flet_notifications.options import (
+    AndroidOptions,
+    DarwinOptions,
+    InterruptionLevel,
+    LinuxOptions,
+    LinuxUrgency,
+    NotificationOptions,
+    Priority,
+    Visibility,
+    WebOptions,
+    WindowsOptions,
+    WindowsScenario,
+)
+from flet_notifications.styles import (
+    AndroidIcon,
+    BigPictureStyle,
+    BigTextStyle,
+    InboxStyle,
+    Message,
+    MessagingStyle,
+    Person,
+    Style,
+)
+from flet_notifications.types import (
+    AndroidScheduleMode,
+    DateTimeComponents,
+    GroupAlertBehavior,
+    Importance,
+    RepeatInterval,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ActiveNotification",
+    "AndroidIcon",
+    "AndroidOptions",
+    "AndroidScheduleMode",
+    "BigPictureStyle",
+    "BigTextStyle",
+    "DarwinOptions",
+    "DateTimeComponents",
+    "GroupAlertBehavior",
+    "Importance",
+    "InboxStyle",
+    "InterruptionLevel",
+    "LaunchDetails",
+    "LinuxOptions",
+    "LinuxUrgency",
+    "LocalNotifications",
+    "Message",
+    "MessagingStyle",
+    "NotificationAction",
+    "NotificationActionInput",
+    "NotificationChannel",
+    "NotificationError",
+    "NotificationErrorCode",
+    "NotificationEvent",
+    "NotificationOptions",
+    "PendingNotification",
+    "Person",
+    "Priority",
+    "RepeatInterval",
+    "ResponseType",
+    "Style",
+    "Visibility",
+    "WebOptions",
+    "WindowsOptions",
+    "WindowsScenario",
+]

flet_notifications-0.1.0/src/flet_notifications/actions.py

@@ -0,0 +1,55 @@
+"""Action buttons and inline-reply inputs for notifications."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass(kw_only=True)
+class NotificationActionInput:
+    """Inline-reply input attached to a notification action.
+
+    Maps to ``AndroidNotificationActionInput`` on Android, the text variant of
+    ``DarwinNotificationAction`` on iOS/macOS and ``WindowsInput`` on Windows.
+    """
+
+    label: str = ""  # placeholder / button title over the text field
+    choices: list[str] = field(default_factory=list)  # quick-reply suggestions
+    allow_free_form_input: bool = True
+    allowed_mime_types: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "label": self.label,
+            "choices": list(self.choices),
+            "allow_free_form_input": self.allow_free_form_input,
+            "allowed_mime_types": list(self.allowed_mime_types),
+        }
+
+
+@dataclass(kw_only=True)
+class NotificationAction:
+    """A button shown on a notification.
+
+    When the button is pressed, ``on_action`` fires with ``action_id == id``.
+    If ``input`` is set, the OS shows an inline-reply field and the typed text
+    arrives as ``NotificationEvent.input``.
+    """
+
+    id: str
+    title: str
+    destructive: bool = False  # iOS/macOS: render as destructive
+    foreground: bool = True  # bring the app to the foreground on press
+    cancel_notification: bool = True  # Android: dismiss the notification
+    input: Optional[NotificationActionInput] = None
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "destructive": self.destructive,
+            "foreground": self.foreground,
+            "cancel_notification": self.cancel_notification,
+            "input": self.input.to_dict() if self.input else None,
+        }

flet_notifications-0.1.0/src/flet_notifications/base.py

@@ -0,0 +1,87 @@
+"""Shared types and helpers for flet-notifications."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+import flet as ft
+
+
+class ResponseType(str, Enum):
+    """Type of a notification response delivered from the OS to the app."""
+
+    TAP = "tap"
+    ACTION = "action"
+    DISMISSED = "dismissed"
+
+
+@dataclass
+class NotificationEvent(ft.Event[ft.EventControlType]):
+    """A notification tap, action-button press or dismissal.
+
+    Delivered to ``on_tap`` / ``on_action`` / ``on_dismissed`` handlers.
+    """
+
+    id: int = 0
+    action_id: str = ""  # "" for a plain tap; the button id for actions
+    payload: str = ""
+    input: str = ""  # inline-reply text, when the action had an input
+    response_type: str = ResponseType.TAP.value
+    # Windows action inputs arrive in the inherited `data` field, keyed by
+    # the input id (Windows leaves `input` null).
+
+
+class NotificationErrorCode:
+    """Stable machine-readable error codes raised by the service."""
+
+    UNSUPPORTED_PLATFORM = "unsupported_platform"
+    INIT_FAILED = "init_failed"
+    SHOW_FAILED = "show_failed"
+    SCHEDULE_FAILED = "schedule_failed"
+    INVALID_ACTION = "invalid_action"
+    INVALID_SCHEDULE = "invalid_schedule"
+    INVALID_STYLE = "invalid_style"
+    INVALID_CHANNEL = "invalid_channel"
+    INVALID_SERVICE_ID = "invalid_service_id"
+    INVALID_OPTION = "invalid_option"
+    CHANNEL_FAILED = "channel_failed"
+    FOREGROUND_SERVICE_FAILED = "foreground_service_failed"
+    QUERY_FAILED = "query_failed"
+    PERMISSION_FAILED = "permission_failed"
+    UNKNOWN_METHOD = "unknown_method"
+
+
+class NotificationError(Exception):
+    """Raised when a notification operation fails.
+
+    ``code`` is a stable machine-readable identifier — see
+    :class:`NotificationErrorCode` for the full list.
+    """
+
+    def __init__(self, code: str, message: str = "") -> None:
+        self.code = code
+        self.message = message
+        super().__init__(f"{code}: {message}" if message else code)
+
+    def __repr__(self) -> str:
+        return f"NotificationError(code={self.code!r}, message={self.message!r})"
+
+
+def check_result(result: object) -> None:
+    """Raise :class:`NotificationError` if a Dart invoke returned an error string.
+
+    Dart service methods return ``"error:<code>:<message>"`` on failure.
+    """
+    if isinstance(result, str) and result.startswith("error:"):
+        _, _, rest = result.partition(":")
+        code, _, message = rest.partition(":")
+        raise NotificationError(code.strip(), message.strip())
+
+
+def to_bool(result: object) -> bool:
+    """Coerce a Dart invoke result to bool (``"true"``/``"false"``)."""
+    check_result(result)
+    if isinstance(result, bool):
+        return result
+    return str(result).strip().lower() == "true"

flet_notifications-0.1.0/src/flet_notifications/channels.py

@@ -0,0 +1,87 @@
+"""Android notification channels."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from flet_notifications.types import Importance
+
+
+@dataclass(kw_only=True)
+class NotificationChannel:
+    """An Android notification channel (required since Android 8.0).
+
+    Sound and vibration are fixed at channel creation; to change them you
+    create a new channel with a new id.
+    """
+
+    id: str
+    name: str
+    description: str = ""
+    group_id: Optional[str] = None
+    importance: Importance = Importance.DEFAULT
+    bypass_dnd: bool = False
+    play_sound: bool = True
+    sound: Optional[str] = None  # raw resource name, e.g. "alert"
+    enable_vibration: bool = True
+    vibration_pattern: Optional[list[int]] = None
+    show_badge: bool = True
+    enable_lights: bool = False
+    led_color: Optional[str] = None  # #RRGGBB
+
+    def __post_init__(self) -> None:
+        if not self.id:
+            raise ValueError("channel id is required")
+        if not self.name:
+            raise ValueError("channel name is required")
+        if self.led_color is not None:
+            self.led_color = _validate_hex(self.led_color)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "group_id": self.group_id,
+            "importance": self.importance.value,
+            "bypass_dnd": self.bypass_dnd,
+            "play_sound": self.play_sound,
+            "sound": self.sound,
+            "enable_vibration": self.enable_vibration,
+            "vibration_pattern": (
+                list(self.vibration_pattern) if self.vibration_pattern else None
+            ),
+            "show_badge": self.show_badge,
+            "enable_lights": self.enable_lights,
+            "led_color": self.led_color,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "NotificationChannel":
+        return cls(
+            id=str(data.get("id", "")),
+            name=str(data.get("name", "")),
+            description=str(data.get("description") or ""),
+            group_id=data.get("groupId") or data.get("group_id"),
+            importance=Importance(data.get("importance", "defaultImportance")),
+            bypass_dnd=bool(data.get("bypass_dnd", False)),
+            play_sound=bool(data.get("play_sound", True)),
+            sound=data.get("sound"),
+            enable_vibration=bool(data.get("enable_vibration", True)),
+            vibration_pattern=data.get("vibration_pattern"),
+            show_badge=bool(data.get("show_badge", True)),
+            enable_lights=bool(data.get("enable_lights", False)),
+            led_color=data.get("led_color"),
+        )
+
+
+def _validate_hex(value: str) -> str:
+    v = value.strip()
+    if not v.startswith("#") or len(v) not in (7, 9):
+        raise ValueError(f"invalid hex color: {value!r}")
+    try:
+        int(v[1:], 16)
+    except ValueError as e:
+        raise ValueError(f"invalid hex color: {value!r}") from e
+    return v