_messaging_utils.py

# Copyright 2017 Google Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Types and utilities used by the messaging (FCM) module."""

from firebase_admin import exceptions


class Notification:
    """A notification that can be included in a message.

    Args:
        title: Title of the notification (optional).
        body: Body of the notification (optional).
        image: Image url of the notification (optional)
    """

    def __init__(self, title=None, body=None, image=None):
        self.title = title
        self.body = body
        self.image = image


class AndroidConfig:
    """Android-specific options that can be included in a message.

    Args:
        collapse_key: Collapse key string for the message (optional). This is an identifier for a
            group of messages that can be collapsed, so that only the last message is sent when
            delivery can be resumed. A maximum of 4 different collapse keys may be active at a
            given time.
        priority: Priority of the message (optional). Must be one of ``high`` or ``normal``.
        ttl: The time-to-live duration of the message (optional). This can be specified
            as a numeric seconds value or a ``datetime.timedelta`` instance.
        restricted_package_name: The package name of the application where the registration tokens
            must match in order to receive the message (optional).
        data: A dictionary of data fields (optional). All keys and values in the dictionary must be
            strings. When specified, overrides any data fields set via ``Message.data``.
        notification: A ``messaging.AndroidNotification`` to be included in the message (optional).
        fcm_options: A ``messaging.AndroidFCMOptions`` to be included in the message (optional).
    """

    def __init__(self, collapse_key=None, priority=None, ttl=None, restricted_package_name=None,
                 data=None, notification=None, fcm_options=None):
        self.collapse_key = collapse_key
        self.priority = priority
        self.ttl = ttl
        self.restricted_package_name = restricted_package_name
        self.data = data
        self.notification = notification
        self.fcm_options = fcm_options


class AndroidNotification:
    """Android-specific notification parameters.

    Args:
        title: Title of the notification (optional). If specified, overrides the title set via
            ``messaging.Notification``.
        body: Body of the notification (optional). If specified, overrides the body set via
            ``messaging.Notification``.
        icon: Icon of the notification (optional).
        color: Color of the notification icon expressed in ``#rrggbb`` form (optional).
        sound: Sound to be played when the device receives the notification (optional). This is
            usually the file name of the sound resource.
        tag: Tag of the notification (optional). This is an identifier used to replace existing
            notifications in the notification drawer. If not specified, each request creates a new
            notification.
        click_action: The action associated with a user click on the notification (optional). If
            specified, an activity with a matching intent filter is launched when a user clicks on
            the notification.
        body_loc_key: Key of the body string in the app's string resources to use to localize the
            body text (optional).
        body_loc_args: A list of resource keys that will be used in place of the format specifiers
            in ``body_loc_key`` (optional).
        title_loc_key: Key of the title string in the app's string resources to use to localize the
            title text (optional).
        title_loc_args: A list of resource keys that will be used in place of the format specifiers
            in ``title_loc_key`` (optional).
        channel_id: channel_id of the notification (optional).
        image: Image url of the notification (optional).
        ticker: Sets the ``ticker`` text, which is sent to accessibility services. Prior to API
            level 21 (Lollipop), sets the text that is displayed in the status bar when the
            notification first arrives (optional).
        sticky: When set to ``False`` or unset, the notification is automatically dismissed when the
            user clicks it in the panel. When set to ``True``, the notification persists even when
            the user clicks it (optional).
        event_timestamp: For notifications that inform users about events with an absolute time
            reference, sets the time that the event in the notification occurred as a
            ``datetime.datetime`` instance. If the ``datetime.datetime`` instance is naive, it
            defaults to be in the UTC timezone. Notifications in the panel are sorted by this time
            (optional).
        local_only: Sets whether or not this notification is relevant only to the current device.
            Some notifications can be bridged to other devices for remote display, such as a Wear OS
            watch. This hint can be set to recommend this notification not be bridged (optional).
            See Wear OS guides:
            https://developer.android.com/training/wearables/notifications/bridger#existing-method-of-preventing-bridging
        priority: Sets the relative priority for this notification. Low-priority notifications may
            be hidden from the user in certain situations. Note this priority differs from
            ``AndroidMessagePriority``. This priority is processed by the client after the message
            has been delivered. Whereas ``AndroidMessagePriority`` is an FCM concept that controls
            when the message is delivered (optional). Must be one of ``default``, ``min``, ``low``,
            ``high``, ``max`` or ``normal``.
        vibrate_timings_millis: Sets the vibration pattern to use. Pass in an array of milliseconds
            to turn the vibrator on or off. The first value indicates the duration to wait before
            turning the vibrator on. The next value indicates the duration to keep the vibrator on.
            Subsequent values alternate between duration to turn the vibrator off and to turn the
            vibrator on. If ``vibrate_timings`` is set and ``default_vibrate_timings`` is set to
            ``True``, the default value is used instead of the user-specified ``vibrate_timings``.
        default_vibrate_timings: If set to ``True``, use the Android framework's default vibrate
            pattern for the notification (optional). Default values are specified in ``config.xml``
            https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml.
            If ``default_vibrate_timings`` is set to ``True`` and ``vibrate_timings`` is also set,
            the default value is used instead of the user-specified ``vibrate_timings``.
        default_sound: If set to ``True``, use the Android framework's default sound for the
            notification (optional). Default values are specified in ``config.xml``
            https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml
        light_settings: Settings to control the notification's LED blinking rate and color if LED is
            available on the device. The total blinking time is controlled by the OS (optional).
        default_light_settings: If set to ``True``, use the Android framework's default LED light
            settings for the notification. Default values are specified in ``config.xml``
            https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml.
            If ``default_light_settings`` is set to ``True`` and ``light_settings`` is also set, the
            user-specified ``light_settings`` is used instead of the default value.
        visibility: Sets the visibility of the notification. Must be either ``private``, ``public``,
            or ``secret``. If unspecified, default to ``private``.
        notification_count: Sets the number of items this notification represents. May be displayed
            as a badge count for Launchers that support badging. See ``NotificationBadge``
            https://developer.android.com/training/notify-user/badges. For example, this might be
            useful if you're using just one notification to represent multiple new messages but you
            want the count here to represent the number of total new messages. If zero or
            unspecified, systems that support badging use the default, which is to increment a
            number displayed on the long-press menu each time a new notification arrives.


    """

    def __init__(self, title=None, body=None, icon=None, color=None, sound=None, tag=None,
                 click_action=None, body_loc_key=None, body_loc_args=None, title_loc_key=None,
                 title_loc_args=None, channel_id=None, image=None, ticker=None, sticky=None,
                 event_timestamp=None, local_only=None, priority=None, vibrate_timings_millis=None,
                 default_vibrate_timings=None, default_sound=None, light_settings=None,
                 default_light_settings=None, visibility=None, notification_count=None):
        self.title = title
        self.body = body
        self.icon = icon
        self.color = color
        self.sound = sound
        self.tag = tag
        self.click_action = click_action
        self.body_loc_key = body_loc_key
        self.body_loc_args = body_loc_args
        self.title_loc_key = title_loc_key
        self.title_loc_args = title_loc_args
        self.channel_id = channel_id
        self.image = image
        self.ticker = ticker
        self.sticky = sticky
        self.event_timestamp = event_timestamp
        self.local_only = local_only
        self.priority = priority
        self.vibrate_timings_millis = vibrate_timings_millis
        self.default_vibrate_timings = default_vibrate_timings
        self.default_sound = default_sound
        self.light_settings = light_settings
        self.default_light_settings = default_light_settings
        self.visibility = visibility
        self.notification_count = notification_count


class LightSettings:
    """Represents settings to control notification LED that can be included in a
    ``messaging.AndroidNotification``.

    Args:
        color: Sets the color of the LED in ``#rrggbb`` or ``#rrggbbaa`` format.
        light_on_duration_millis: Along with ``light_off_duration``, defines the blink rate of LED
            flashes.
        light_off_duration_millis: Along with ``light_on_duration``, defines the blink rate of LED
            flashes.
    """
    def __init__(self, color, light_on_duration_millis,
                 light_off_duration_millis):
        self.color = color
        self.light_on_duration_millis = light_on_duration_millis
        self.light_off_duration_millis = light_off_duration_millis


class AndroidFCMOptions:
    """Options for features provided by the FCM SDK for Android.

    Args:
        analytics_label: contains additional options for features provided by the FCM Android SDK
            (optional).
    """

    def __init__(self, analytics_label=None):
        self.analytics_label = analytics_label


class WebpushConfig:
    """Webpush-specific options that can be included in a message.

    Args:
        headers: A dictionary of headers (optional). Refer `Webpush Specification`_ for supported
            headers.
        data: A dictionary of data fields (optional). All keys and values in the dictionary must be
            strings. When specified, overrides any data fields set via ``Message.data``.
        notification: A ``messaging.WebpushNotification`` to be included in the message (optional).
        fcm_options: A ``messaging.WebpushFCMOptions`` instance to be included in the message
            (optional).

    .. _Webpush Specification: https://tools.ietf.org/html/rfc8030#section-5
    """

    def __init__(self, headers=None, data=None, notification=None, fcm_options=None):
        self.headers = headers
        self.data = data
        self.notification = notification
        self.fcm_options = fcm_options


class WebpushNotificationAction:
    """An action available to the users when the notification is presented.

    Args:
        action: Action string.
        title: Title string.
        icon: Icon URL for the action (optional).
    """

    def __init__(self, action, title, icon=None):
        self.action = action
        self.title = title
        self.icon = icon


class WebpushNotification:
    """Webpush-specific notification parameters.

    Refer to the `Notification Reference`_ for more information.

    Args:
        title: Title of the notification (optional). If specified, overrides the title set via
            ``messaging.Notification``.
        body: Body of the notification (optional). If specified, overrides the body set via
            ``messaging.Notification``.
        icon: Icon URL of the notification (optional).
        actions: A list of ``messaging.WebpushNotificationAction`` instances (optional).
        badge: URL of the image used to represent the notification when there is
            not enough space to display the notification itself (optional).
        data: Any arbitrary JSON data that should be associated with the notification (optional).
        direction: The direction in which to display the notification (optional). Must be either
            'auto', 'ltr' or 'rtl'.
        image: The URL of an image to be displayed in the notification (optional).
        language: Notification language (optional).
        renotify: A boolean indicating whether the user should be notified after a new
            notification replaces an old one (optional).
        require_interaction: A boolean indicating whether a notification should remain active
            until the user clicks or dismisses it, rather than closing automatically (optional).
        silent: ``True`` to indicate that the notification should be silent (optional).
        tag: An identifying tag on the notification (optional).
        timestamp_millis: A timestamp value in milliseconds on the notification (optional).
        vibrate: A vibration pattern for the device's vibration hardware to emit when the
            notification fires (optional). The pattern is specified as an integer array.
        custom_data: A dict of custom key-value pairs to be included in the notification
            (optional)

    .. _Notification Reference: https://developer.mozilla.org/en-US/docs/Web/API\
        /notification/Notification
    """

    def __init__(self, title=None, body=None, icon=None, actions=None, badge=None, data=None,
                 direction=None, image=None, language=None, renotify=None,
                 require_interaction=None, silent=None, tag=None, timestamp_millis=None,
                 vibrate=None, custom_data=None):
        self.title = title
        self.body = body
        self.icon = icon
        self.actions = actions
        self.badge = badge
        self.data = data
        self.direction = direction
        self.image = image
        self.language = language
        self.renotify = renotify
        self.require_interaction = require_interaction
        self.silent = silent
        self.tag = tag
        self.timestamp_millis = timestamp_millis
        self.vibrate = vibrate
        self.custom_data = custom_data


class WebpushFCMOptions:
    """Options for features provided by the FCM SDK for Web.

    Args:
        link: The link to open when the user clicks on the notification. Must be an HTTPS URL
            (optional).
    """

    def __init__(self, link=None):
        self.link = link


class APNSConfig:
    """APNS-specific options that can be included in a message.

    Refer to `APNS Documentation`_ for more information.

    Args:
        headers: A dictionary of headers (optional).
        payload: A ``messaging.APNSPayload`` to be included in the message (optional).
        fcm_options: A ``messaging.APNSFCMOptions`` instance to be included in the message
            (optional).

    .. _APNS Documentation: https://developer.apple.com/library/content/documentation\
        /NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html
    """

    def __init__(self, headers=None, payload=None, fcm_options=None):
        self.headers = headers
        self.payload = payload
        self.fcm_options = fcm_options


class APNSPayload:
    """Payload of an APNS message.

    Args:
        aps: A ``messaging.Aps`` instance to be included in the payload.
        **kwargs: Arbitrary keyword arguments to be included as custom fields in the payload
            (optional).
    """

    def __init__(self, aps, **kwargs):
        self.aps = aps
        self.custom_data = kwargs


class Aps:
    """Aps dictionary to be included in an APNS payload.

    Args:
        alert: A string or a ``messaging.ApsAlert`` instance (optional).
        badge: A number representing the badge to be displayed with the message (optional).
        sound: Name of the sound file to be played with the message or a
            ``messaging.CriticalSound`` instance (optional).
        content_available: A boolean indicating whether to configure a background update
            notification (optional).
        category: String identifier representing the message type (optional).
        thread_id: An app-specific string identifier for grouping messages (optional).
        mutable_content: A boolean indicating whether to support mutating notifications at
            the client using app extensions (optional).
        custom_data: A dict of custom key-value pairs to be included in the Aps dictionary
            (optional).
    """

    def __init__(self, alert=None, badge=None, sound=None, content_available=None, category=None,
                 thread_id=None, mutable_content=None, custom_data=None):
        self.alert = alert
        self.badge = badge
        self.sound = sound
        self.content_available = content_available
        self.category = category
        self.thread_id = thread_id
        self.mutable_content = mutable_content
        self.custom_data = custom_data


class CriticalSound:
    """Critical alert sound configuration that can be included in ``messaging.Aps``.

    Args:
        name: The name of a sound file in your app's main bundle or in the ``Library/Sounds``
            folder of your app's container directory. Specify the string ``default`` to play the
            system sound.
        critical: Set to ``True`` to set the critical alert flag on the sound configuration
            (optional).
        volume: The volume for the critical alert's sound. Must be a value between 0.0 (silent)
            and 1.0 (full volume) (optional).
    """

    def __init__(self, name, critical=None, volume=None):
        self.name = name
        self.critical = critical
        self.volume = volume


class ApsAlert:
    """An alert that can be included in ``messaging.Aps``.

    Args:
        title: Title of the alert (optional). If specified, overrides the title set via
            ``messaging.Notification``.
        subtitle: Subtitle of the alert (optional).
        body: Body of the alert (optional). If specified, overrides the body set via
            ``messaging.Notification``.
        loc_key: Key of the body string in the app's string resources to use to localize the
            body text (optional).
        loc_args: A list of resource keys that will be used in place of the format specifiers
            in ``loc_key`` (optional).
        title_loc_key: Key of the title string in the app's string resources to use to localize the
            title text (optional).
        title_loc_args: A list of resource keys that will be used in place of the format specifiers
            in ``title_loc_key`` (optional).
        action_loc_key: Key of the text in the app's string resources to use to localize the
            action button text (optional).
        launch_image: Image for the notification action (optional).
        custom_data: A dict of custom key-value pairs to be included in the ApsAlert dictionary
            (optional)
    """

    def __init__(self, title=None, subtitle=None, body=None, loc_key=None, loc_args=None,
                 title_loc_key=None, title_loc_args=None, action_loc_key=None, launch_image=None,
                 custom_data=None):
        self.title = title
        self.subtitle = subtitle
        self.body = body
        self.loc_key = loc_key
        self.loc_args = loc_args
        self.title_loc_key = title_loc_key
        self.title_loc_args = title_loc_args
        self.action_loc_key = action_loc_key
        self.launch_image = launch_image
        self.custom_data = custom_data


class APNSFCMOptions:
    """Options for features provided by the FCM SDK for iOS.

    Args:
        analytics_label: contains additional options for features provided by the FCM iOS SDK
            (optional).
        image: contains the URL of an image that is going to be displayed in a notification
            (optional).
    """

    def __init__(self, analytics_label=None, image=None):
        self.analytics_label = analytics_label
        self.image = image


class FCMOptions:
    """Options for features provided by SDK.

    Args:
        analytics_label: contains additional options to use across all platforms (optional).
    """

    def __init__(self, analytics_label=None):
        self.analytics_label = analytics_label


class ThirdPartyAuthError(exceptions.UnauthenticatedError):
    """APNs certificate or web push auth key was invalid or missing."""

    def __init__(self, message, cause=None, http_response=None):
        exceptions.UnauthenticatedError.__init__(self, message, cause, http_response)


class QuotaExceededError(exceptions.ResourceExhaustedError):
    """Sending limit exceeded for the message target."""

    def __init__(self, message, cause=None, http_response=None):
        exceptions.ResourceExhaustedError.__init__(self, message, cause, http_response)


class SenderIdMismatchError(exceptions.PermissionDeniedError):
    """The authenticated sender ID is different from the sender ID for the registration token."""

    def __init__(self, message, cause=None, http_response=None):
        exceptions.PermissionDeniedError.__init__(self, message, cause, http_response)


class UnregisteredError(exceptions.NotFoundError):
    """App instance was unregistered from FCM.

    This usually means that the token used is no longer valid and a new one must be used."""

    def __init__(self, message, cause=None, http_response=None):
        exceptions.NotFoundError.__init__(self, message, cause, http_response)