parse-stack-next 4.5.0

data/lib/parse/model/classes/audience.rb

@@ -0,0 +1,262 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Note: Do not require "../object" here - this file is loaded from object.rb
+# and adding that require would create a circular dependency.
+
+module Parse
+  # This class represents the data and columns contained in the standard Parse
+  # `_Audience` collection. Audiences are pre-defined groups of installations
+  # that can be targeted for push notifications. They store query constraints
+  # that define which installations belong to the audience.
+  #
+  # Audiences are useful for:
+  # - Reusable push targets (e.g., "VIP Users", "Beta Testers")
+  # - A/B testing different user segments
+  # - Marketing campaigns to specific demographics
+  #
+  # == Caching
+  #
+  # Audience queries are cached by default to improve push notification performance.
+  # The cache has a configurable TTL (default: 5 minutes).
+  #
+  # @example Configure cache TTL
+  #   Parse::Audience.cache_ttl = 600  # 10 minutes
+  #
+  # @example Clear the cache
+  #   Parse::Audience.clear_cache!
+  #
+  # @example Bypass cache for a specific lookup
+  #   audience = Parse::Audience.find_by_name("VIP Users", cache: false)
+  #
+  # The default schema for the {Audience} class is as follows:
+  #   class Parse::Audience < Parse::Object
+  #      # See Parse::Object for inherited properties...
+  #
+  #      property :name
+  #      property :query, :object  # The Installation query constraints
+  #   end
+  #
+  # @example Creating an audience
+  #   audience = Parse::Audience.new(
+  #     name: "iOS VIP Users",
+  #     query: { "deviceType" => "ios", "vip" => true }
+  #   )
+  #   audience.save
+  #
+  # @example Targeting an audience with push
+  #   Parse::Push.new
+  #     .to_audience("iOS VIP Users")
+  #     .with_alert("Exclusive offer!")
+  #     .send!
+  #
+  # @see Parse::Push#to_audience
+  # @see Parse::Object
+  class Audience < Parse::Object
+    parse_class Parse::Model::CLASS_AUDIENCE
+
+    # Default cache TTL in seconds (5 minutes)
+    DEFAULT_CACHE_TTL = 300
+
+    class << self
+      # @return [Integer] the cache TTL in seconds (default: 300)
+      attr_writer :cache_ttl
+
+      def cache_ttl
+        @cache_ttl ||= DEFAULT_CACHE_TTL
+      end
+
+      # Clear the audience cache
+      # @return [void]
+      def clear_cache!
+        cache_mutex.synchronize do
+          @audience_cache = {}
+          @cache_timestamps = {}
+        end
+      end
+
+      # Get an audience from cache or fetch from server
+      # @param name [String] the audience name
+      # @param cache [Boolean] whether to use cache (default: true)
+      # @return [Parse::Audience, nil] the audience or nil if not found
+      def cache_fetch(name, cache: true)
+        return find_by_name_uncached(name) unless cache
+
+        cache_mutex.synchronize do
+          @audience_cache ||= {}
+          @cache_timestamps ||= {}
+
+          # Cleanup expired entries periodically to prevent memory growth
+          cleanup_expired_cache_entries
+
+          cached = @audience_cache[name]
+          timestamp = @cache_timestamps[name]
+
+          # Check if cache is valid
+          if timestamp && (Time.now.to_i - timestamp) < cache_ttl
+            return cached
+          end
+
+          # Fetch and cache (fetch happens inside lock - acceptable for short TTL cache)
+          audience = find_by_name_uncached(name)
+          @audience_cache[name] = audience
+          @cache_timestamps[name] = Time.now.to_i
+
+          audience
+        end
+      end
+
+      # Remove expired entries from cache to prevent memory leaks
+      # Called automatically during cache_fetch, but can also be called manually
+      # @return [Integer] number of entries removed
+      def cleanup_expired_cache!
+        cache_mutex.synchronize do
+          cleanup_expired_cache_entries
+        end
+      end
+
+      # Thread-safe mutex for cache operations
+      # @return [Mutex]
+      def cache_mutex
+        @cache_mutex ||= Mutex.new
+      end
+
+      private
+
+      # Internal method to cleanup expired cache entries (must be called within synchronize block)
+      # @return [Integer] number of entries removed
+      def cleanup_expired_cache_entries
+        return 0 unless @cache_timestamps
+
+        now = Time.now.to_i
+        expired_keys = @cache_timestamps.select { |_key, ts| now - ts >= cache_ttl }.keys
+
+        expired_keys.each do |key|
+          @audience_cache&.delete(key)
+          @cache_timestamps.delete(key)
+        end
+
+        expired_keys.size
+      end
+
+      def find_by_name_uncached(name)
+        first(name: name)
+      end
+    end
+
+    # @!attribute name
+    # The display name of this audience.
+    # @return [String] The audience name.
+    property :name
+
+    # @!attribute query
+    # The query constraints that define which installations belong to this audience.
+    # This is stored as a hash matching the Installation query format.
+    # @return [Hash] The query constraint hash.
+    # @example
+    #   audience.query = { "deviceType" => "ios", "appVersion" => { "$gte" => "2.0" } }
+    property :query, :object
+
+    # Alias for query to match Parse Server naming conventions.
+    # @return [Hash] The query constraint hash.
+    def query_constraint
+      query
+    end
+
+    # Set the query constraint.
+    # @param constraints [Hash] The query constraint hash.
+    def query_constraint=(constraints)
+      self.query = constraints
+    end
+
+    class << self
+      # Find an audience by name (uses cache by default).
+      # @param name [String] the audience name
+      # @param cache [Boolean] whether to use cache (default: true)
+      # @return [Parse::Audience, nil] the audience or nil if not found
+      # @example
+      #   audience = Parse::Audience.find_by_name("VIP Users")
+      #   audience = Parse::Audience.find_by_name("VIP Users", cache: false)  # Bypass cache
+      def find_by_name(name, cache: true)
+        cache_fetch(name, cache: cache)
+      end
+
+      # Get the count of installations matching an audience's query.
+      # @param audience_name [String] the audience name
+      # @return [Integer] the count of matching installations
+      # @raise [Parse::Push::AudienceNotFound] if no audience exists with the
+      #   given name. Previously returned 0 on miss, which was indistinguishable
+      #   from "audience exists but matches nothing."
+      # @example
+      #   count = Parse::Audience.installation_count("VIP Users")
+      def installation_count(audience_name)
+        audience = find_by_name(audience_name)
+        if audience.nil?
+          raise Parse::Push::AudienceNotFound,
+                "Audience '#{audience_name}' not found in _Audience collection"
+        end
+        return 0 unless audience.query.present?
+
+        q = Parse::Installation.query
+        audience.query.each do |key, value|
+          q.where(key.to_sym => value)
+        end
+        q.count
+      end
+
+      # Get a query for installations matching an audience.
+      # @param audience_name [String] the audience name
+      # @return [Parse::Query] a query for matching installations
+      # @raise [Parse::Push::AudienceNotFound] if no audience exists with the
+      #   given name. Previously returned an unconstrained Installation query
+      #   on miss, which silently elevated the result set from "matches this
+      #   audience" to "every Installation" — the same fail-open footgun as
+      #   {Parse::Push#to_audience}.
+      # @example
+      #   installations = Parse::Audience.installations("VIP Users").all
+      def installations(audience_name)
+        audience = find_by_name(audience_name)
+        if audience.nil?
+          raise Parse::Push::AudienceNotFound,
+                "Audience '#{audience_name}' not found in _Audience collection"
+        end
+        q = Parse::Installation.query
+        if audience.query.present?
+          audience.query.each do |key, value|
+            q.where(key.to_sym => value)
+          end
+        end
+        q
+      end
+    end
+
+    # Get the count of installations matching this audience's query.
+    # @return [Integer] the count of matching installations
+    # @example
+    #   audience = Parse::Audience.first
+    #   puts "#{audience.name} has #{audience.installation_count} members"
+    def installation_count
+      return 0 unless query.present?
+
+      q = Parse::Installation.query
+      query.each do |key, value|
+        q.where(key.to_sym => value)
+      end
+      q.count
+    end
+
+    # Get a query for installations matching this audience.
+    # @return [Parse::Query] a query for matching installations
+    # @example
+    #   audience.installations.each { |i| puts i.device_token }
+    def installations
+      q = Parse::Installation.query
+      if query.present?
+        query.each do |key, value|
+          q.where(key.to_sym => value)
+        end
+      end
+      q
+    end
+  end
+end

data/lib/parse/model/classes/installation.rb

@@ -0,0 +1,363 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+# Note: Do not require "../object" here - this file is loaded from object.rb
+# and adding that require would create a circular dependency.
+
+module Parse
+  # This class represents the data and columns contained in the standard Parse
+  # `_Installation` collection. This class is also responsible for managing the
+  # device tokens for mobile devices in order to use push notifications. All queries done
+  # to send pushes using Parse::Push are performed against the Installation collection.
+  # An installation object represents an instance of your app being installed
+  # on a device. These objects are used to store subscription data for
+  # installations which have subscribed to one or more push notification channels.
+  #
+  # The default schema for {Installation} is as follows:
+  #
+  #   class Parse::Installation < Parse::Object
+  #      # See Parse::Object for inherited properties...
+  #
+  #     property :gcm_sender_id, field: :GCMSenderId
+  #     property :app_identifier
+  #     property :app_name
+  #     property :app_version
+  #     property :app_build_number
+  #     property :badge, :integer
+  #     property :channels, :array
+  #     property :device_token
+  #     property :device_token_last_modified, :integer
+  #     property :device_type, enum: [:ios, :android, :osx, :tvos, :watchos, :web, :expo, :win, :other, :unknown, :unsupported]
+  #     property :installation_id
+  #     property :locale_identifier
+  #     property :parse_version
+  #     property :push_type
+  #     property :time_zone, :timezone
+  #
+  #     has_one :session, ->{ where(installation_id: i.installation_id) }, scope_only: true
+  #   end
+  # @see Push
+  # @see Parse::Object
+  class Installation < Parse::Object
+    parse_class Parse::Model::CLASS_INSTALLATION
+    # @!attribute gcm_sender_id
+    # This field only has meaning for Android installations that use the GCM
+    # push type. It is reserved for directing Parse to send pushes to this
+    # installation with an alternate GCM sender ID. This field should generally
+    # not be set unless you are uploading installation data from another push
+    # provider. If you set this field, then you must set the GCM API key
+    # corresponding to this GCM sender ID in your Parse application’s push settings.
+    # @return [String]
+    property :gcm_sender_id, field: :GCMSenderId
+
+    # @!attribute app_identifier
+    # A unique identifier for this installation’s client application. In iOS, this is the Bundle Identifier.
+    # @return [String]
+    property :app_identifier
+
+    # @!attribute app_name
+    # The display name of the client application to which this installation belongs.
+    # @return [String]
+    property :app_name
+
+    # @!attribute app_version
+    # The version string of the client application to which this installation belongs.
+    # @return [String]
+    property :app_version
+
+    # @!attribute app_build_number
+    # The build number of the client application to which this installation belongs.
+    # @return [String]
+    property :app_build_number
+
+    # @!attribute badge
+    # A number field representing the last known application badge for iOS installations.
+    # @return [Integer]
+    property :badge, :integer
+
+    # @!attribute channels
+    # An array of the channels to which a device is currently subscribed.
+    # Note that **channelUris** (the Microsoft-generated push URIs for Windows devices) is
+    # not supported at this time.
+    # @return [Array]
+    property :channels, :array
+
+    # @!attribute device_token
+    # The Apple or Google generated token used to deliver messages to the APNs
+    # or GCM push networks respectively.
+    # @return [String]
+    property :device_token
+
+    # @!attribute device_token_last_modified
+    # @return [Integer] number of seconds since token modified
+    property :device_token_last_modified, :integer
+
+    # @!attribute device_type
+    # The type of device: "ios", "android", "osx", "tvos", "watchos", "web", "expo", "win",
+    # "other", "unknown", or "unsupported".
+    # This property is implemented as a Parse::Stack enumeration.
+    # @return [String]
+    property :device_type, enum: [:ios, :android, :osx, :tvos, :watchos, :web, :expo, :win, :other, :unknown, :unsupported]
+
+    # @!attribute installation_id
+    # Universally Unique Identifier (UUID) for the device used by Parse. It
+    # must be unique across all of an app’s installations. (readonly).
+    # @return [String]
+    property :installation_id
+
+    # @!attribute locale_identifier
+    # The locale for this device.
+    # @return [String]
+    property :locale_identifier
+
+    # @!attribute parse_version
+    # The version of the Parse SDK which this installation uses.
+    # @return [String]
+    property :parse_version
+
+    # @!attribute push_type
+    # This field is reserved for directing Parse to the push delivery network
+    # to be used. If the device is registered to receive pushes via GCM, this
+    # field will be marked “gcm”. If this device is not using GCM, and is
+    # using Parse’s push notification service, it will be blank (readonly).
+    # @return [String]
+    property :push_type
+
+    # @!attribute time_zone
+    # The current time zone where the target device is located. This should be an IANA time zone identifier
+    # or a {Parse::TimeZone} instance.
+    # @return [Parse::TimeZone]
+    property :time_zone, :timezone
+
+    # @!attribute session
+    # Returns the corresponding {Parse::Session} associated with this installation, if any exists.
+    # This is implemented as a has_one association to the Session class using the {installation_id}.
+    # @version 1.7.1
+    # @return [Parse::Session] The associated {Parse::Session} that might be tied to this installation
+    has_one :session, -> { where(installation_id: i.installation_id) }, scope_only: true
+
+    # =========================================================================
+    # Channel Management - Class Methods
+    # =========================================================================
+
+    class << self
+      # List all unique channel names across all installations.
+      # @return [Array<String>] array of channel names
+      # @example
+      #   all_channels = Parse::Installation.all_channels
+      #   # => ["news", "sports", "weather"]
+      def all_channels
+        distinct(:channels)
+      end
+
+      # Count the number of installations subscribed to a specific channel.
+      # @param channel [String] the channel name to count subscribers for
+      # @return [Integer] the number of subscribers
+      # @example
+      #   count = Parse::Installation.subscribers_count("news")
+      #   # => 1250
+      def subscribers_count(channel)
+        query(:channels.in => [channel]).count
+      end
+
+      # Get a query for installations subscribed to a specific channel.
+      # @param channel [String] the channel name to find subscribers for
+      # @return [Parse::Query] a query scoped to the channel's subscribers
+      # @example
+      #   # Get all iOS subscribers to the "news" channel
+      #   installations = Parse::Installation.subscribers("news")
+      #     .where(device_type: "ios")
+      #     .all
+      def subscribers(channel)
+        query(:channels.in => [channel])
+      end
+
+      # =========================================================================
+      # Device Type Scopes
+      # =========================================================================
+      # Note: ios and android scopes are automatically created by the enum property:
+      #   property :device_type, enum: [:ios, :android, :osx, :tvos, :watchos, :web, :expo, :win, :other, :unknown, :unsupported]
+      # This creates: Installation.ios, Installation.android, etc.
+
+      # Query scope for a specific device type.
+      # @param type [String, Symbol] the device type (ios, android, osx, tvos, watchos, web, expo, win, other, unknown, unsupported)
+      # @return [Parse::Query] a query for the specified device type
+      # @example
+      #   mac_devices = Parse::Installation.by_device_type(:osx).all
+      def by_device_type(type)
+        query(device_type: type.to_s)
+      end
+
+      # =========================================================================
+      # Badge Management
+      # =========================================================================
+
+      # Reset badge count for all installations in a channel.
+      # @param channel [String] the channel name
+      # @return [Integer] the number of installations updated
+      # @example
+      #   Parse::Installation.reset_badges_for_channel("news")
+      def reset_badges_for_channel(channel)
+        installations = subscribers(channel).where(:badge.gt => 0).all
+        installations.each do |installation|
+          installation.badge = 0
+          installation.save
+        end
+        installations.count
+      end
+
+      # Reset badge count for all installations of a specific device type.
+      # @param type [String, Symbol] the device type (default: :ios since badges are primarily iOS)
+      # @return [Integer] the number of installations updated
+      # @example
+      #   Parse::Installation.reset_all_badges
+      #   Parse::Installation.reset_all_badges(:android)
+      def reset_all_badges(type = :ios)
+        installations = by_device_type(type).where(:badge.gt => 0).all
+        installations.each do |installation|
+          installation.badge = 0
+          installation.save
+        end
+        installations.count
+      end
+
+      # =========================================================================
+      # Stale Token Detection
+      # =========================================================================
+
+      # Query for installations with stale (old) device tokens.
+      # Useful for cleaning up installations that are likely no longer active.
+      # @param days [Integer] number of days since last token modification (default: 90)
+      # @return [Parse::Query] a query for installations with old tokens
+      # @example
+      #   # Find installations not updated in 90 days
+      #   stale = Parse::Installation.stale_tokens.all
+      #
+      #   # Find installations not updated in 30 days
+      #   stale = Parse::Installation.stale_tokens(days: 30).all
+      def stale_tokens(days: 90)
+        cutoff = Time.now - (days * 24 * 60 * 60)
+        query(:updated_at.lt => cutoff)
+      end
+
+      # Count installations with stale tokens.
+      # @param days [Integer] number of days since last update (default: 90)
+      # @return [Integer] count of stale installations
+      # @example
+      #   count = Parse::Installation.stale_count(days: 60)
+      def stale_count(days: 90)
+        stale_tokens(days: days).count
+      end
+
+      # Delete all installations with stale tokens.
+      # Use with caution - this permanently removes installation records.
+      # @param days [Integer] number of days since last update (default: 90)
+      # @return [Integer] the number of installations deleted
+      # @example
+      #   # Clean up installations not updated in 180 days
+      #   deleted = Parse::Installation.cleanup_stale_tokens!(days: 180)
+      def cleanup_stale_tokens!(days: 90)
+        installations = stale_tokens(days: days).all
+        installations.each(&:destroy)
+        installations.count
+      end
+    end
+
+    # =========================================================================
+    # Channel Management - Instance Methods
+    # =========================================================================
+
+    # Subscribe this installation to one or more channels.
+    # The changes are automatically saved to the server.
+    # @param channel_names [Array<String>] the channel names to subscribe to
+    # @return [Boolean] true if the save was successful
+    # @example
+    #   installation.subscribe("news", "weather")
+    #   installation.subscribe(["sports", "updates"])
+    def subscribe(*channel_names)
+      self.channels ||= []
+      self.channels = (self.channels + channel_names.flatten.map(&:to_s)).uniq
+      save
+    end
+
+    # Unsubscribe this installation from one or more channels.
+    # The changes are automatically saved to the server.
+    # @param channel_names [Array<String>] the channel names to unsubscribe from
+    # @return [Boolean] true if the save was successful, or true if no channels were set
+    # @example
+    #   installation.unsubscribe("news")
+    #   installation.unsubscribe("sports", "weather")
+    def unsubscribe(*channel_names)
+      return true unless channels.present?
+      self.channels = channels - channel_names.flatten.map(&:to_s)
+      save
+    end
+
+    # Check if this installation is subscribed to a specific channel.
+    # @param channel [String] the channel name to check
+    # @return [Boolean] true if subscribed to the channel
+    # @example
+    #   if installation.subscribed_to?("news")
+    #     puts "Subscribed to news!"
+    #   end
+    def subscribed_to?(channel)
+      channels&.include?(channel.to_s) || false
+    end
+
+    # =========================================================================
+    # Badge Management - Instance Methods
+    # =========================================================================
+
+    # Reset the badge count to 0 and save.
+    # @return [Boolean] true if save was successful
+    # @example
+    #   installation.reset_badge!
+    def reset_badge!
+      self.badge = 0
+      save
+    end
+
+    # Increment the badge count and save.
+    # @param amount [Integer] amount to increment by (default: 1)
+    # @return [Boolean] true if save was successful
+    # @example
+    #   installation.increment_badge!
+    #   installation.increment_badge!(5)
+    def increment_badge!(amount = 1)
+      self.badge = (badge || 0) + amount
+      save
+    end
+
+    # =========================================================================
+    # Stale Token Detection - Instance Methods
+    # =========================================================================
+
+    # Check if this installation's token is considered stale.
+    # @param days [Integer] number of days to consider stale (default: 90)
+    # @return [Boolean] true if the installation hasn't been updated in the given days
+    # @example
+    #   if installation.stale?
+    #     puts "This installation may no longer be active"
+    #   end
+    def stale?(days: 90)
+      return false if updated_at.nil?
+      cutoff = Time.now - (days * 24 * 60 * 60)
+      updated_at < cutoff
+    end
+
+    # Get the number of days since this installation was last updated.
+    # @return [Integer, nil] days since last update, or nil if no updated_at
+    # @example
+    #   puts "Last active #{installation.days_since_update} days ago"
+    def days_since_update
+      return nil if updated_at.nil?
+      ((Time.now - updated_at.to_time) / (24 * 60 * 60)).to_i
+    end
+
+    # =========================================================================
+    # Device Type Helpers - Instance Methods
+    # =========================================================================
+    # Note: ios? and android? predicates are automatically created by the enum property:
+    #   property :device_type, enum: [:ios, :android, :osx, :tvos, :watchos, :web, :expo, :win, :other, :unknown, :unsupported]
+    # This creates: installation.ios?, installation.android?, etc.
+  end
+end