/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

namespace push {};

/// Object representing the PushManager used to manage subscriptions
///
/// The `PushManager` object is the main interface provided by this crate
/// it allow consumers to manage push subscriptions. It exposes methods that
/// interact with the [`autopush server`](https:///autopush.readthedocs.io/en/latest/)
/// and persists state representing subscriptions.
interface PushManager {
    /// Creates a new [`PushManager`] object, not subscribed to any
    /// channels
    ///
    /// # Arguments
    ///
    ///   - `config`: The PushConfiguration for the PushManager
    ///
    /// # Errors
    /// Returns an error in the following cases:
    ///   - PushManager is unable to open the `database_path` given
    [Throws=PushApiError]
    constructor(PushConfiguration config);

    /// Subscribes to a new channel and gets the Subscription Info block
    ///
    /// # Arguments
    ///   - `scope` - Site scope string
    ///   - `server_key` - optional VAPID public key to "lock" subscriptions (defaults to "" for no key)
    ///
    /// # Returns
    /// A Subscription response that includes the following:
    ///   - A URL that can be used to deliver push messages
    ///   - A cryptographic key that can be used to encrypt messages
    ///     that would then be decrypted using the [`PushManager::decrypt`] function
    ///
    /// # Errors
    /// Returns an error in the following cases:
    ///   - PushManager was unable to access its persisted storage
    ///   - An error occurred sending a subscription request to the autopush server
    ///   - An error occurred generating or deserializing the cryptographic keys
    [Throws=PushApiError]
    SubscriptionResponse subscribe([ByRef] string scope, [ByRef] optional string? app_server_sey = null);


    /// Retrieves an existing push subscription
    ///
    /// # Arguments
    ///   - `scope` - Site scope string
    ///
    /// # Returns
    /// A Subscription response that includes the following:
    ///   - A URL that can be used to deliver push messages
    ///   - A cryptographic key that can be used to encrypt messages
    ///     that would then be decrypted using the [`PushManager::decrypt`] function
    ///
    /// # Errors
    /// Returns an error in the following cases:
    ///   - PushManager was unable to access its persisted storage
    ///   - An error occurred generating or deserializing the cryptographic keys
    [Throws=PushApiError]
    SubscriptionResponse? get_subscription([ByRef] string scope);

    /// Unsubscribe from given scope, ending that subscription for the user.
    ///
    /// # Arguments
    ///   - `scope` - The scope for the channel to remove
    ///
    /// # Returns
    /// Returns a boolean. Boolean is False if the subscription was already
    /// terminated in the past.
    ///
    /// # Errors
    /// Returns an error in the following cases:
    ///   - An error occurred sending an unsubscribe request to the autopush server
    ///   - An error occurred accessing the PushManager's persisted storage
    [Throws=PushApiError]
    boolean unsubscribe([ByRef] string scope);

    /// Unsubscribe all channels for the user
    ///
    /// # Errors
    /// Returns an error in the following cases:
    ///   - The PushManager does not contain a valid UAID
    ///   - An error occurred sending an unsubscribe request to the autopush server
    ///   - An error occurred accessing the PushManager's persisted storage
    [Throws=PushApiError]
    void unsubscribe_all();

    /// Updates the Native OS push registration ID.
    ///
    /// # Arguments:
    ///   - `new_token` - the new Native OS push registration ID
    ///
    /// # Errors
    /// Return an error in the following cases:
    ///   - The PushManager does not contain a valid UAID
    ///   - An error occurred sending an update request to the autopush server
    ///   - An error occurred accessing the PushManager's persisted storage
    [Throws=PushApiError]
    void update([ByRef] string registration_token);

    /// Verifies the connection state
    ///
    /// **NOTE**: This does not resubscribe to any channels
    /// it only returns the list of channels that the client should
    /// re-subscribe to.
    ///
    /// # Returns
    /// Returns a list of [`PushSubscriptionChanged`]
    /// indicating the channels the consumer the client should re-subscribe
    /// to. If the list is empty, the client's connection was verified
    /// successfully, and the client does not need to resubscribe
    ///
    /// # Errors
    /// Return an error in the following cases:
    ///   - The PushManager does not contain a valid UAID
    ///   - An error occurred sending an channel list retrieval request to the autopush server
    ///   - An error occurred accessing the PushManager's persisted storage
    [Throws=PushApiError]
    sequence<PushSubscriptionChanged> verify_connection(optional boolean force_verify = false);

    /// Decrypts a raw push message.
    ///
    /// This accepts the content of a Push Message (from websocket or via Native Push systems).
    /// # Arguments:
    ///   - `payload`: The Push payload as received by the client from Push.
    ///
    /// # Returns
    /// Decrypted message body
    ///
    /// # Errors
    /// Returns an error in the following cases:
    ///   - The PushManager does not contain a valid UAID
    ///   - There are no records associated with the UAID the [`PushManager`] contains
    ///   - An error occurred while decrypting the message
    ///   - An error occurred accessing the PushManager's persisted storage
    [Throws=PushApiError]
    DecryptResponse decrypt(record<DOMString, string> payload);
};

/// Key Information that can be used to encrypt payloads
dictionary KeyInfo {
    string auth;
    string p256dh;
};

/// Subscription Information, the endpoint to send push messages to and
/// the key information that can be used to encrypt payloads
dictionary SubscriptionInfo {
    string endpoint;
    KeyInfo keys;
};

/// The subscription response object returned from [`PushManager::subscribe`]
dictionary SubscriptionResponse {
    string channel_id;
    SubscriptionInfo subscription_info;
};

/// An dictionary describing the push subscription that changed, the caller
/// will receive a list of [`PushSubscriptionChanged`] when calling
/// [`PushManager::verify_connection`], one entry for each channel that the
/// caller should resubscribe to
dictionary PushSubscriptionChanged {
    string channel_id;
    string scope;
};

dictionary DecryptResponse {
    sequence<i8> result;
    string scope;
};

/// The main Error returned from the Push component, each
/// variant describes a different error
[Error]
enum PushApiError {
    "UAIDNotRecognizedError",

    "RecordNotFoundError",

    "InternalError"
};

/// The types of supported native bridges.
///
/// FCM = Google Android Firebase Cloud Messaging
/// ADM = Amazon Device Messaging for FireTV
/// APNS = Apple Push Notification System for iOS
///
/// Please contact services back-end for any additional bridge protocols.
///
enum BridgeType {
    "Fcm",
    "Adm",
    "Apns",
};

dictionary PushConfiguration {
    string server_host;
    PushHttpProtocol http_protocol;
    BridgeType bridge_type;
    string sender_id;
    string database_path;
    u64? verify_connection_rate_limiter;
};

/// Supported protocols for push
/// "Https" is default, and "Http" is only
///  supported  for tests
enum PushHttpProtocol {
    "Https",
    "Http"
};