flet-notifications 0.1.0__py3-none-any.whl

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/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/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/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

flet_notifications/events.py

@@ -0,0 +1,43 @@
+"""Event payload types delivered from the Dart side."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from flet_notifications.base import NotificationEvent
+
+
+@dataclass
+class PendingNotification:
+    """A scheduled notification that has not been delivered yet.
+
+    Returned by :meth:`LocalNotifications.get_pending_notifications`.
+    """
+
+    id: int
+    title: str = ""
+    body: str = ""
+    payload: str = ""
+
+
+@dataclass
+class ActiveNotification:
+    """A notification currently shown in the notification tray."""
+
+    id: int = 0
+    channel_id: str = ""
+    group_key: str = ""
+    tag: str = ""
+    title: str = ""
+    body: str = ""
+    payload: str = ""
+    big_text: str = ""
+
+
+@dataclass
+class LaunchDetails:
+    """Why/how the app was launched, if a notification launched it."""
+
+    did_notification_launch_app: bool = False
+    notification: Optional[NotificationEvent] = None