firebase-admin-sdk 0.1.0 → 0.1.1

data/lib/firebase/admin/messaging/apns_config.rb

@@ -0,0 +1,38 @@
+module Firebase
+  module Admin
+    module Messaging
+      # APNS-specific options that can be included in a {Message}.
+      #
+      # Refer to `APNS Documentation` for more information.
+      # @see https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html
+      class APNSConfig
+        # @return [Hash{Symbol,String => String}, nil]
+        #   A collection of APNs headers. Header values must be strings.
+        attr_accessor :headers
+
+        # @return [APNSPayload, nil]
+        #   An APNs payload to be included in the message.
+        attr_accessor :payload
+
+        # @return [APNSFCMOptions, nil]
+        #   Options for features provided by the FCM SDK for iOS.
+        attr_accessor :fcm_options
+
+        # Initializes an {APNSConfig}.
+        #
+        # @param [Hash{Symbol,String => String}, nil] headers
+        #   A collection of APNs headers (optional).
+        #   Header keys and values must be strings.
+        # @param [APNSPayload, nil] payload
+        #   An APNs payload to be included in the message (optional).
+        # @param [APNSFCMOptions, nil] fcm_options
+        #   Options for features provided by the FCM SDK for iOS (optional).
+        def initialize(headers: nil, payload: nil, fcm_options: nil)
+          self.headers = headers
+          self.payload = payload
+          self.fcm_options = fcm_options
+        end
+      end
+    end
+  end
+end

data/lib/firebase/admin/messaging/apns_fcm_options.rb

@@ -0,0 +1,27 @@
+module Firebase
+  module Admin
+    module Messaging
+      # Options for features provided by the FCM SDK for iOS.
+      class APNSFCMOptions
+        # @return [String, nil]
+        #   The label associated with the message's analytics data.
+        attr_accessor :analytics_label
+
+        # @return [String, nil]
+        #   URL of an image to be displayed in the notification.
+        attr_accessor :image
+
+        # Initializes an {APNSFCMOptions}.
+        #
+        # @param [String, nil] analytics_label
+        #   The label associated with the message's analytics data (optional).
+        # @param [String, nil] image
+        #   URL of an image to be displayed in the notification (optional).
+        def initialize(analytics_label: nil, image: nil)
+          self.analytics_label = analytics_label
+          self.image = image
+        end
+      end
+    end
+  end
+end

data/lib/firebase/admin/messaging/apns_payload.rb

@@ -0,0 +1,28 @@
+module Firebase
+  module Admin
+    module Messaging
+      # Represents the payload of an APNs message.
+      #
+      # Mainly consists of the `aps` dictionary. But may also contain other arbitrary custom keys.
+      #
+      class APNSPayload
+        # @return [APS] The aps instance to be included in the payload.
+        attr_accessor :aps
+
+        # @return [Hash] Custom fields to include in the payload.
+        attr_accessor :data
+
+        # Initializes a payload.
+        #
+        # @param [APS] aps
+        #   An {APS} instance to be included in the payload.
+        # @param [Hash, nil] data
+        #   Arbitrary keyword arguments to be included as custom fields in the payload.
+        def initialize(aps:, data: nil)
+          @aps = aps
+          @data = data
+        end
+      end
+    end
+  end
+end

data/lib/firebase/admin/messaging/aps.rb

@@ -0,0 +1,82 @@
+module Firebase
+  module Admin
+    module Messaging
+      # Aps dictionary to be included in an APNS payload.
+      class APS
+        # @return [APSAlert, String, nil]
+        #   Alert to be included in the message.
+        attr_accessor :alert
+
+        # @return [Integer, nil]
+        #   Badge to be displayed with the message. Set to 0 to remove the badge. When not specified, the badge will
+        #   remain unchanged.
+        attr_accessor :badge
+
+        # @return [String, CriticalSound, nil]
+        #   Sound to be played with the message.
+        attr_accessor :sound
+
+        # @return [Boolean, nil]
+        #   Specifies whether to configure a background update notification.
+        attr_accessor :content_available
+
+        # @return [Boolean, nil]
+        #   Specifies whether to set the `mutable-content` property on the message so the clients can modify the
+        #   notification via app extensions.
+        attr_accessor :mutable_content
+
+        # @return [String, nil]
+        #   Type of the notification.
+        attr_accessor :category
+
+        # @return [String, nil]
+        #   An app-specific identifier for grouping notifications.
+        attr_accessor :thread_id
+
+        # @return [Hash]
+        #   App-specific custom fields.
+        attr_accessor :custom_data
+
+        # Initializes an {APS}.
+        #
+        # @param [APSAlert, String, nil] alert
+        #   Alert to be included in the message (optional).
+        # @param [Integer, nil] badge
+        #   Badge to be displayed with the message (optional).
+        #   Set to 0 to remove the badge. When not specified, the badge will remain unchanged.
+        # @param [String, CriticalSound, nil] sound
+        #   Sound to be played with the message (optional).
+        # @param [Boolean, nil] content_available
+        #   Specifies whether to configure a background update notification (optional).
+        # @param [Boolean, nil] mutable_content
+        #   Specifies whether to set the `mutable-content` property on the message so the clients can modify the
+        #   notification via app extensions (optional).
+        # @param [String, nil] category
+        #   Type of the notification (optional).
+        # @param [String, nil] thread_id
+        #   An app-specific identifier for grouping notifications (optional).
+        # @param [Hash, nil] custom_data
+        #   App-specific custom fields (optional).
+        def initialize(
+          alert: nil,
+          badge: nil,
+          sound: nil,
+          content_available: nil,
+          mutable_content: nil,
+          category: nil,
+          thread_id: nil,
+          custom_data: nil
+        )
+          self.alert = alert
+          self.badge = badge
+          self.sound = sound
+          self.content_available = content_available
+          self.mutable_content = mutable_content
+          self.category = category
+          self.thread_id = thread_id
+          self.custom_data = custom_data
+        end
+      end
+    end
+  end
+end

data/lib/firebase/admin/messaging/aps_alert.rb

@@ -0,0 +1,110 @@
+module Firebase
+  module Admin
+    module Messaging
+      # An alert that can be included in an {APS}.
+      class APSAlert
+        # @return [String, nil]
+        #   Title of the alert. If specified, overrides the title set via {Notification}.
+        attr_accessor :title
+
+        # @return [String, nil]
+        #   Subtitle of the alert.
+        attr_accessor :subtitle
+
+        # @return [String, nil]
+        #   Body of the alert. If specified, overrides the body set via {Notification}.
+        attr_accessor :body
+
+        # @return [String, nil]
+        #   Key of the body string in the app's string resources to use to localize the body text.
+        attr_accessor :loc_key
+
+        # @return [Array<String>, nil]
+        #   A list of resource keys that will be used in place of the format specifiers in {loc_key}.
+        attr_accessor :loc_args
+
+        # @return [String, nil]
+        #   Key of the title string in the app's string resources to use to localize the title text.
+        attr_accessor :title_loc_key
+
+        # @return [Array<String>, nil]
+        #   A list of resource keys that will be used in place of the format specifiers in {title_loc_key}.
+        attr_accessor :title_loc_args
+
+        # @return [String, nil]
+        #   Key of the subtitle string in the app's string resources to use to localize the subtitle text.
+        attr_accessor :subtitle_loc_key
+
+        # @return [Array<String>, nil]
+        #   A list of resource keys that will be used in place of the format specifiers in {subtitle_loc_key}.
+        attr_accessor :subtitle_loc_args
+
+        # @return [String, nil]
+        #   Key of the text in the app's string resources to use to localize the action button text.
+        attr_accessor :action_loc_key
+
+        # @return [String, nil]
+        #   Image for the notification action.
+        attr_accessor :launch_image
+
+        # @return [Hash, nil]
+        #   A Hash of custom key-value pairs to be included in the {APSAlert}
+        attr_accessor :custom_data
+
+        # Initializes an {APSAlert}.
+        #
+        # @param [String, nil] title
+        #   Title of the alert (optional). If specified, overrides the title set via {Notification}.
+        # @param [String, nil] subtitle
+        #   Subtitle of the alert (optional).
+        # @param [String, nil] body
+        #   Body of the alert (optional). If specified, overrides the body set via {Notification}.
+        # @param [String, nil] loc_key
+        #   Key of the body string in the app's string resources to use to localize the body text (optional).
+        # @param [Array<String>, nil] loc_args
+        #   List of resource keys that will be used in place of the format specifiers in {loc_key} (optional).
+        # @param [String, nil] title_loc_key
+        #   Key of the title string in the app's string resources to use to localize the title text (optional).
+        # @param [Array<String>, nil] title_loc_args
+        #   List of resource keys that will be used in place of the format specifiers in {title_loc_key} (optional).
+        # @param [String, nil] subtitle_loc_key
+        #   Key of the subtitle string in the app's string resources to use to localize the subtitle text (optional).
+        # @param [Array<String>, nil] subtitle_loc_args
+        #   List of resource keys that will be used in place of the format specifiers in {subtitle_loc_key} (optional).
+        # @param [String, nil] action_loc_key
+        #   Key of the text in the app's string resources to use to localize the action button text (optional).
+        # @param [String, nil] launch_image
+        #   Image for the notification action (optional).
+        # @param [Hash, nil] custom_data
+        #   A Hash of custom key-value pairs to be included in the {APSAlert} (optional).
+        def initialize(
+          title: nil,
+          subtitle: nil,
+          body: nil,
+          loc_key: nil,
+          loc_args: nil,
+          title_loc_key: nil,
+          title_loc_args: nil,
+          subtitle_loc_key: nil,
+          subtitle_loc_args: nil,
+          action_loc_key: nil,
+          launch_image: nil,
+          custom_data: nil
+        )
+          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.subtitle_loc_key = subtitle_loc_key
+          self.subtitle_loc_args = subtitle_loc_args
+          self.action_loc_key = action_loc_key
+          self.launch_image = launch_image
+          self.custom_data = custom_data
+        end
+      end
+    end
+  end
+end

data/lib/firebase/admin/messaging/client.rb

@@ -0,0 +1,181 @@
+module Firebase
+  module Admin
+    module Messaging
+      # A client for communicating with the Firebase Cloud Messaging service.
+      class Client
+        def initialize(app)
+          @project_id = app.project_id
+          @http_client = Firebase::Admin::Internal::HTTPClient.new(credentials: app.credentials)
+          @message_encoder = MessageEncoder.new
+        end
+
+        # Sends a message via Firebase Cloud Messaging (FCM).
+        #
+        # If the `dry_run` flag is set, the message will not be actually delivered to the recipients.
+        # Instead FCM performs all the usual validations, and emulates the send operation.
+        #
+        # @param [Message] message A message to send.
+        # @param [Boolean] dry_run A flag indicating whether to run the operation in dry run mode.
+        #
+        # @return [String] A message id that uniquely identifies the message.
+        def send_one(message, dry_run: false)
+          body = {
+            validate_only: dry_run,
+            message: @message_encoder.encode(message)
+          }
+          res = @http_client.post(send_url, body, FCM_HEADERS)
+          res.body["name"]
+        rescue Faraday::Error => e
+          raise parse_fcm_error(e)
+        end
+
+        # Sends the given list of messages via Firebase Cloud Messaging (FCM) as a single batch.
+        #
+        # If the `dry_run` flag is set, the messages will not be actually delivered to the recipients.
+        # Instead FCM performs all the usual validations, and emulates the send operation.
+        #
+        # @param [Array<Message>] messages An array of messages to send.
+        # @param [Boolean] dry_run A flag indicating whether to run the operation in dry run mode.
+        #
+        # @return [BatchResponse] A batch response.
+        def send_all(messages, dry_run: false)
+          raise NotImplementedError
+        end
+
+        # Sends the given multicast message to all tokens via Firebase Cloud Messaging (FCM).
+        #
+        # If the `dry_run` flag is set, the message will not be actually delivered to the recipients.
+        # Instead FCM performs all the usual validations, and emulates the send operation.
+        #
+        # @param [MulticastMessage] multicast_message A multicast message to send.
+        # @param [Boolean] dry_run A flag indicating whether to run the operation in dry run mode.
+        #
+        # @return [BatchResponse] A batch response.
+        def send_multicast(multicast_message, dry_run: false)
+          messages = multicast_message.tokens.map do |token|
+            Message.new(
+              token: token,
+              data: multicast_message.data,
+              notification: multicast_message.notification,
+              android: multicast_message.android,
+              apns: multicast_message.apns,
+              fcm_options: multicast_message.fcm_options
+            )
+          end
+          send_all(messages, dry_run: dry_run)
+        end
+
+        # Subscribes a list of registration tokens to an FCM topic.
+        #
+        # @param [Array<String>, String] tokens An array of device registration tokens (max 1000).
+        # @param [String] topic Name of the topic to subscribe to. May contain the `/topics` prefix.
+        #
+        # @return [TopicManagementResponse] A topic management response.
+        def subscribe_to_topic(tokens, topic)
+          make_topic_mgmt_request(tokens, topic, "batchAdd")
+        end
+
+        # Unsubscribes a list of registration tokens from an FCM topic.
+        #
+        # @param [Array<String>, String] tokens An array of device registration tokens (max 1000).
+        # @param [String] topic Name of the topic to unsubscribe from. May contain the `/topics` prefix.
+        #
+        # @return [TopicManagementResponse] A topic management response.
+        def unsubscribe_from_topic(tokens, topic)
+          make_topic_mgmt_request(tokens, topic, "batchRemove")
+        end
+
+        private
+
+        # @return [String] The firebase cloud messaging send endpoint url.
+        def send_url
+          "#{FCM_HOST}/v1/projects/#{@project_id}/messages:send"
+        end
+
+        # @return [String] The topic management endpoint url.
+        def topic_mgmt_url(operation)
+          "#{IID_HOST}/iid/v1:#{operation}"
+        end
+
+        def make_topic_mgmt_request(tokens, topic, operation)
+          tokens = [tokens] if tokens.is_a?(String)
+
+          unless tokens.is_a?(Array) && !tokens.empty?
+            raise ArgumentError, "tokens must be a string or non-empty array of strings."
+          end
+
+          unless tokens.all?(String)
+            raise ArgumentError, "tokens must be a non-empty array of strings."
+          end
+
+          unless topic.is_a?(String) && !topic.empty?
+            raise ArgumentError, "topic must be a non-empty string."
+          end
+
+          unless %w[batchAdd batchRemove].include?(operation)
+            raise ArgumentError, "operation is invalid"
+          end
+
+          uri = topic_mgmt_url(operation)
+          res = @http_client.post(uri, {
+            to: @message_encoder.sanitize_topic_name(topic, strip_prefix: false),
+            registration_tokens: tokens
+          }, IID_HEADERS)
+          TopicManagementResponse.new(res)
+        end
+
+        # @param [Faraday::Error] err
+        def parse_fcm_error(err)
+          msg, info = parse_platform_error(err.response_status, err.response_body)
+          return err if info.empty?
+
+          details = info["details"] || []
+          detail = details.find { |detail| detail["@type"] == "type.googleapis.com/google.firebase.fcm.v1.FcmError" }
+          return err unless detail.is_a?(Hash)
+
+          cls = FCM_ERROR_TYPES[detail["errorCode"] || ""] || Error
+          cls.new(msg, info)
+        rescue JSON::ParserError
+          Error.new("HTTP response is not json.", err.response)
+        end
+
+        # Parses an HTTP error response from a Google Cloud Platform API and extracts the error code
+        # and message fields.
+        #
+        # @param [Integer] status_code
+        # @param [String] body
+        # @return Array<String,Hash>
+        def parse_platform_error(status_code, body)
+          parsed = JSON.parse(body)
+          data = parsed.is_a?(Hash) ? parsed : {}
+          details = data.fetch("error", {})
+          msg = details.fetch("message", "Unexpected HTTP response with status #{status_code}; body: #{body}")
+          [msg, details]
+        end
+
+        FCM_HOST = "https://fcm.googleapis.com"
+        FCM_HEADERS = {"X-GOOG-API-FORMAT-VERSION": "2"}
+        IID_HOST = "https://iid.googleapis.com"
+        IID_HEADERS = {"access_token_auth" => "true"}
+
+        FCM_ERROR_TYPES = {
+          "APNS_AUTH_ERROR" => ThirdPartyAuthError,
+          "INVALID_ARGUMENT" => InvalidArgumentError,
+          "QUOTA_EXCEEDED" => QuotaExceededError,
+          "SENDER_ID_MISMATCH" => SenderIdMismatchError,
+          "THIRD_PARTY_AUTH_ERROR" => ThirdPartyAuthError,
+          "UNREGISTERED" => UnregisteredError,
+          "UNSPECIFIED_ERROR" => UnspecifiedError
+        }
+      end
+    end
+
+    class App
+      # Gets the Firebase Cloud Messaging client for this App.
+      # @return [Firebase::Admin::Messaging::Client]
+      def messaging
+        @messaging_client ||= Messaging::Client.new(self)
+      end
+    end
+  end
+end