instagram_connect 0.2.1 → 0.3.1

data/lib/instagram_connect/ingest/handlers/messaging_postbacks.rb

@@ -0,0 +1,24 @@
+module InstagramConnect
+  class Ingest
+    module Handlers
+      # A tap on an ice breaker, a persistent-menu item, or a template button.
+      # Postbacks carry no message of their own, so there is nothing to persist
+      # yet — the host callback is the whole point.
+      class MessagingPostbacks < Base
+        def self.dedupe_key(event)
+          event.dig("postback", "mid").presence
+        end
+
+        def call
+          notify(config.on_postback, {
+            account_id: account.id,
+            sender_id: event.dig("sender", "id"),
+            payload: event.dig("postback", "payload"),
+            title: event.dig("postback", "title")
+          })
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/instagram_connect/ingest/handlers/messaging_referral.rb

@@ -0,0 +1,42 @@
+module InstagramConnect
+  class Ingest
+    module Handlers
+      # The customer arrived through an ig.me link, an ad, or a product tag.
+      # A referral opens the 24-hour messaging window even before they type
+      # anything, so it has to bump the thread's activity.
+      #
+      # Only a standalone referral reaches here — one nested inside a message
+      # or postback stays with its parent event (see Registry).
+      class MessagingReferral < Base
+        def self.dedupe_key(event)
+          ref = event.dig("referral", "ref").presence or return nil
+
+          "#{event.dig('sender', 'id')}:#{ref}:#{event['timestamp']}"
+        end
+
+        def call
+          conversation.register_referral(ref: payload["ref"], at: referred_at)
+          conversation
+        end
+
+        private
+
+        def payload
+          event["referral"] || {}
+        end
+
+        def igsid
+          event.dig("sender", "id").to_s
+        end
+
+        def referred_at
+          envelope.occurred_at || Time.current
+        end
+
+        def conversation
+          @conversation ||= InstagramConnect::Conversation.locate(account: account, igsid: igsid)
+        end
+      end
+    end
+  end
+end

data/lib/instagram_connect/ingest/handlers/messaging_seen.rb

@@ -0,0 +1,37 @@
+module InstagramConnect
+  class Ingest
+    module Handlers
+      # A read receipt: the customer has seen everything up to this message.
+      class MessagingSeen < Base
+        def self.dedupe_key(event)
+          mid = event.dig("read", "mid").presence or return nil
+
+          "#{event.dig('sender', 'id')}:#{mid}"
+        end
+
+        def call
+          conversation.mark_read_by_customer(at: seen_at, mid: mid)
+          conversation
+        end
+
+        private
+
+        def mid
+          event.dig("read", "mid").to_s
+        end
+
+        def igsid
+          event.dig("sender", "id").to_s
+        end
+
+        def seen_at
+          envelope.occurred_at || Time.current
+        end
+
+        def conversation
+          @conversation ||= InstagramConnect::Conversation.locate(account: account, igsid: igsid)
+        end
+      end
+    end
+  end
+end

data/lib/instagram_connect/ingest/handlers/story_insights.rb

@@ -0,0 +1,62 @@
+module InstagramConnect
+  class Ingest
+    module Handlers
+      # A story expired, and Meta sent its final metrics with the notification.
+      #
+      # This is the only durable capture path there is. Story insights are
+      # retrievable from the API for 24 hours; after that the numbers do not
+      # exist anywhere. So the snapshot is written here, inside ingest, rather
+      # than handed to a job that might be delayed past the point of no return.
+      class StoryInsights < Base
+        def self.dedupe_key(event)
+          event.dig("value", "media_id").presence
+        end
+
+        def self.requires_dedupe_key?
+          true
+        end
+
+        def call
+          # The story may well have been posted from a phone rather than through
+          # this app, so its media row might not exist yet.
+          InstagramConnect::MediaItem.record(
+            account: account, ig_media_id: media_id, media_product_type: "STORY"
+          )
+
+          InstagramConnect::InsightSnapshot.record(
+            account: account,
+            subject_type: "story",
+            subject_ref: media_id,
+            period: "lifetime",
+            period_start: captured_at.to_date,
+            source: "webhook",
+            metrics: metrics,
+            empty: metrics.empty?,
+            captured_at: captured_at
+          )
+        end
+
+        private
+
+        def value
+          event["value"] || {}
+        end
+
+        def media_id
+          value["media_id"].to_s
+        end
+
+        # Everything except the identifier is a metric. Meta omits a metric it
+        # will not report rather than sending a zero, and that distinction is
+        # preserved by copying the payload as-is instead of filling defaults.
+        def metrics
+          @metrics ||= value.except("media_id")
+        end
+
+        def captured_at
+          envelope.occurred_at || Time.current
+        end
+      end
+    end
+  end
+end

data/lib/instagram_connect/ingest/handlers/unknown.rb

@@ -0,0 +1,19 @@
+module InstagramConnect
+  class Ingest
+    module Handlers
+      # Anything the gem does not parse yet, or an entry belonging to no
+      # connected account. The event is banked verbatim rather than dropped:
+      # Meta never re-delivers, so replaying the row later is the only way to
+      # recover it once a handler exists.
+      #
+      # The dispatcher marks these `unhandled` without calling `#call` — this
+      # class exists so the registry always resolves to something, and so the
+      # ledger records which handler was chosen.
+      class Unknown < Base
+        def call
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/instagram_connect/ingest/registry.rb

@@ -0,0 +1,93 @@
+module InstagramConnect
+  class Ingest
+    # Maps a webhook field to the handler that parses it, and infers the field
+    # for messaging events (Meta delivers all of them under `entry.messaging`
+    # regardless of which subscription triggered them, so the field has to be
+    # recovered from the event's shape).
+    module Registry
+      HANDLERS = {
+        "messages" => Handlers::Messages,
+        "message_echoes" => Handlers::Messages,
+        "messaging_postbacks" => Handlers::MessagingPostbacks,
+        "message_reactions" => Handlers::MessageReactions,
+        "messaging_seen" => Handlers::MessagingSeen,
+        "messaging_referral" => Handlers::MessagingReferral,
+        "messaging_optins" => Handlers::MessagingOptins,
+        "messaging_handover" => Handlers::MessagingHandover,
+        "comments" => Handlers::Comments,
+        "live_comments" => Handlers::Comments,
+        "mentions" => Handlers::Mentions,
+        "story_insights" => Handlers::StoryInsights
+      }.freeze
+
+      # Every field the gem knows Meta can send on the `instagram` object.
+      # Fields without a handler are still worth subscribing to: they bank as
+      # `unhandled` rows and replay once a handler ships, whereas an
+      # unsubscribed field is gone for good — Meta does not store `mentions` or
+      # `story_insights` notifications, and re-delivers nothing.
+      KNOWN_FIELDS = %w[
+        messages
+        message_echoes
+        message_reactions
+        messaging_postbacks
+        messaging_seen
+        messaging_referral
+        messaging_optins
+        messaging_handover
+        messaging_policy_enforcement
+        response_feedback
+        standby
+        comments
+        live_comments
+        mentions
+        story_insights
+      ].freeze
+
+      # Shape tests in priority order. `is_echo` must be checked before the
+      # plain `message` case, since an echo carries a message too.
+      MESSAGING_SHAPES = [
+        [ "message_echoes", ->(e) { e["message"] && e.dig("message", "is_echo") } ],
+        [ "messages", ->(e) { e["message"] } ],
+        [ "message_reactions", ->(e) { e["reaction"] } ],
+        [ "messaging_postbacks", ->(e) { e["postback"] } ],
+        [ "messaging_seen", ->(e) { e["read"] } ],
+        [ "messaging_referral", ->(e) { e["referral"] } ],
+        [ "messaging_optins", ->(e) { e["optin"] } ],
+        [ "messaging_handover", lambda { |e|
+          e["pass_thread_control"] || e["take_thread_control"] || e["request_thread_control"]
+        } ]
+      ].freeze
+
+      UNKNOWN_FIELD = "unknown".freeze
+
+      module_function
+
+      def handler_for(field)
+        HANDLERS.fetch(field, Handlers::Unknown)
+      end
+
+      def handled?(field)
+        HANDLERS.key?(field)
+      end
+
+      # The fields a host should subscribe its Page to. Everything the gem
+      # knows about, handled or not — see KNOWN_FIELDS.
+      def subscribable_fields
+        KNOWN_FIELDS
+      end
+
+      def handled_fields
+        HANDLERS.keys
+      end
+
+      # `message.referral` and `postback.referral` are nested inside their
+      # parent event and stay with it; only a standalone `referral` is a
+      # referral event in its own right, which is why the shape tests run in
+      # order rather than checking every key independently.
+      def messaging_field_for(event)
+        found = MESSAGING_SHAPES.find { |(_field, test)| test.call(event) }
+        found ? found.first : UNKNOWN_FIELD
+      end
+    end
+  end
+end

data/lib/instagram_connect/ingest/summary.rb

@@ -0,0 +1,75 @@
+module InstagramConnect
+  class Ingest
+    # What one webhook delivery produced. Behaves as a Hash so the return value
+    # of Ingest.call stays compatible with hosts written against 0.2.x, which
+    # read summary[:messages] and friends.
+    class Summary
+      COUNTERS = {
+        "messages" => :messages,
+        "message_echoes" => :messages,
+        "messaging_postbacks" => :postbacks,
+        "comments" => :comments,
+        "live_comments" => :comments
+      }.freeze
+
+      attr_accessor :messages, :comments, :postbacks, :duplicates, :unhandled,
+                    :failed, :callback_errors
+
+      def initialize
+        @messages = 0
+        @comments = 0
+        @postbacks = 0
+        @duplicates = 0
+        @unhandled = 0
+        @failed = 0
+        @callback_errors = 0
+      end
+
+      def count(field)
+        counter = COUNTERS[field]
+        return if counter.nil?
+
+        public_send(:"#{counter}=", public_send(counter) + 1)
+      end
+
+      # 0.2.x reported one `skipped` number covering both "we have seen this
+      # already" and "we do not parse this". They are different problems now —
+      # duplicates are healthy, unhandled events are a backlog to replay — but
+      # the combined figure is kept so existing hosts keep working.
+      def skipped
+        duplicates + unhandled
+      end
+
+      def to_h
+        {
+          messages: messages,
+          comments: comments,
+          postbacks: postbacks,
+          skipped: skipped,
+          duplicates: duplicates,
+          unhandled: unhandled,
+          failed: failed,
+          callback_errors: callback_errors
+        }
+      end
+
+      # Implicit conversion, not just the explicit #to_h: it is what makes a
+      # Summary behave as a Hash for callers (and matchers) written against the
+      # plain hash 0.2.x returned.
+      alias_method :to_hash, :to_h
+
+      def [](key)
+        to_h[key.to_sym]
+      end
+
+      def ==(other)
+        other.respond_to?(:to_h) ? to_h == other.to_h : super
+      end
+
+      def each(&block)
+        to_h.each(&block)
+      end
+      include Enumerable
+    end
+  end
+end

data/lib/instagram_connect/ingest.rb

@@ -1,112 +1,34 @@
 module InstagramConnect
-  # Parses a verified Meta webhook payload and persists it into the engine's
-  # chat models, deduping on Meta's message id. After persistence it fires the
-  # configured host handlers (on_message / on_comment / on_postback) so the host
-  # can layer extras (notifications, AI replies) on top.
+  # Turns a verified Meta webhook payload into persisted rows, and fires the
+  # configured host callbacks (on_message / on_comment / on_postback) so the
+  # host can layer notifications, AI drafting or CRM linking on top.
   #
-  # Returns a summary hash of what was processed.
+  # Every event is banked on InstagramConnect::WebhookEvent before anything
+  # parses it. That is what makes an unparsed or mis-parsed event recoverable:
+  # Meta neither stores nor re-delivers webhooks, so anything dropped here is
+  # gone permanently. See Ingest::Dispatcher for the walk.
+  #
+  # Returns a Summary, which reads like the plain hash 0.2.x returned.
   class Ingest
     def self.call(payload:, config: InstagramConnect.configuration)
-      new(config).call(payload)
-    end
-
-    def initialize(config)
-      @config = config
-    end
-
-    def call(payload)
-      summary = { messages: 0, comments: 0, postbacks: 0, skipped: 0 }
-      Array(payload && payload["entry"]).each do |entry|
-        account = account_for(entry)
-        if account.nil?
-          summary[:skipped] += 1
-          next
-        end
-        Array(entry["messaging"]).each { |event| ingest_messaging(account, event, summary) }
-        Array(entry["changes"]).each { |change| ingest_change(account, change, summary) }
-      end
-      summary
-    end
-
-    private
-
-    attr_reader :config
-
-    def account_for(entry)
-      id = entry["id"].to_s
-      Account.find_by(ig_user_id: id) || Account.find_by(page_id: id)
-    end
-
-    def ingest_messaging(account, event, summary)
-      if event["message"]
-        ingest_message(account, event, summary)
-      elsif event["postback"]
-        invoke(config.on_postback, build_postback(account, event))
-        summary[:postbacks] += 1
-      else
-        summary[:skipped] += 1
-      end
-    end
-
-    def ingest_message(account, event, summary)
-      msg = event["message"]
-      mid = msg["mid"].to_s
-      if mid.empty? || !InboundMessage.claim(ig_message_id: mid, account_id: account.id)
-        summary[:skipped] += 1
-        return
-      end
-
-      echo = msg["is_echo"] ? true : false
-      igsid = (echo ? event.dig("recipient", "id") : event.dig("sender", "id")).to_s
-      conversation = Conversation.locate(account: account, igsid: igsid)
-      message = Message.create!(
-        conversation: conversation,
-        direction: echo ? "outbound" : "inbound",
-        status: echo ? "sent" : "received",
-        source: echo ? "operator_app" : "inbound",
-        kind: "dm",
-        body: msg["text"],
-        ig_message_id: mid,
-        media_status: media?(msg) ? "pending" : "none"
-      )
-      conversation.register_message(message)
-      invoke(config.on_message, message) unless echo
-      summary[:messages] += 1
-    end
-
-    def ingest_change(account, change, summary)
-      unless change["field"] == "comments"
-        summary[:skipped] += 1
-        return
-      end
-      value = change["value"] || {}
-      comment = Comment.record(
-        account: account,
-        comment_id: value["id"].to_s,
-        media_id: value.dig("media", "id"),
-        text: value["text"],
-        from_username: value.dig("from", "username"),
-        parent_id: value["parent_id"]
-      )
-      invoke(config.on_comment, comment)
-      summary[:comments] += 1
-    end
-
-    def media?(msg)
-      Array(msg["attachments"]).any?
-    end
-
-    def build_postback(account, event)
-      {
-        account_id: account.id,
-        sender_id: event.dig("sender", "id"),
-        payload: event.dig("postback", "payload"),
-        title: event.dig("postback", "title")
-      }
-    end
-
-    def invoke(handler, arg)
-      handler.call(arg) if handler.respond_to?(:call)
+      Dispatcher.new(config).call(payload)
     end
   end
 end
+
+require_relative "ingest/envelope"
+require_relative "ingest/summary"
+require_relative "ingest/handlers/base"
+require_relative "ingest/handlers/messages"
+require_relative "ingest/handlers/messaging_postbacks"
+require_relative "ingest/handlers/message_reactions"
+require_relative "ingest/handlers/messaging_seen"
+require_relative "ingest/handlers/messaging_referral"
+require_relative "ingest/handlers/messaging_optins"
+require_relative "ingest/handlers/messaging_handover"
+require_relative "ingest/handlers/comments"
+require_relative "ingest/handlers/mentions"
+require_relative "ingest/handlers/story_insights"
+require_relative "ingest/handlers/unknown"
+require_relative "ingest/registry"
+require_relative "ingest/dispatcher"

data/lib/instagram_connect/media/attaching.rb

@@ -0,0 +1,57 @@
+require "marcel"
+require "stringio"
+
+module InstagramConnect
+  module Media
+    # Turns fetched bytes into a stored file, or into an honest reason why not.
+    #
+    # The rule that matters here: when the declared Content-Type and the actual
+    # magic bytes disagree, the magic bytes win. A Content-Type header is
+    # metadata anyone can set; the first few bytes of the file are what the file
+    # actually is. Trusting the header is how a host ends up serving an HTML
+    # document from an <img> tag.
+    module Attaching
+      Result = Struct.new(:ok, :mime, :size, :error, keyword_init: true) do
+        def ok? = ok
+      end
+
+      module_function
+
+      def evaluate(body:, declared_mime:, filename: nil, config: InstagramConnect.configuration)
+        bytes = body.to_s
+        return failure("empty") if bytes.empty?
+
+        mime = sniff(bytes, filename: filename, declared: declared_mime)
+        return failure("type_not_allowed:#{mime}") unless allowed?(mime, config)
+        return failure("too_large:#{bytes.bytesize}") unless within_size?(mime, bytes.bytesize, config)
+
+        Result.new(ok: true, mime: mime, size: bytes.bytesize)
+      end
+
+      def sniff(bytes, filename: nil, declared: nil)
+        sniffed = ::Marcel::MimeType.for(StringIO.new(bytes), name: filename)
+        # Marcel falls back to this when it recognises nothing, in which case the
+        # declared type is the only information available and is better than
+        # nothing.
+        return declared.to_s.split(";").first.to_s.strip if sniffed == "application/octet-stream" && declared.present?
+
+        sniffed
+      end
+
+      def allowed?(mime, config)
+        allowed = config.allowed_media_types
+        allowed.blank? || allowed.include?(mime)
+      end
+
+      # Both Meta's per-type ceiling and the host's own cap have to hold. The
+      # host's exists so an adopter can be stricter than Meta, never looser.
+      def within_size?(mime, bytes, config)
+        Limits.within_size?(mime, bytes) && bytes <= config.media_max_bytes.to_i
+      end
+
+      def failure(reason)
+        Result.new(ok: false, error: reason)
+      end
+    end
+  end
+end

data/lib/instagram_connect/media/limits.rb

@@ -0,0 +1,46 @@
+module InstagramConnect
+  module Media
+    # Meta's ceilings, in one place, read by the composer, the send path and the
+    # client so the numbers cannot drift apart.
+    module Limits
+      IMAGE_MAX_BYTES = 8 * 1024 * 1024
+      AUDIO_VIDEO_MAX_BYTES = 25 * 1024 * 1024
+      ATTACHMENTS_MAX = 10
+
+      # BYTES, not characters. An emoji-heavy 400-character reply is over the
+      # limit and Meta rejects the whole send, so anything measuring this with
+      # String#length is measuring the wrong thing.
+      TEXT_MAX_BYTES = 1000
+
+      IMAGE_TYPES = %w[image/jpeg image/png image/gif].freeze
+      AUDIO_TYPES = %w[audio/aac audio/mp4 audio/mpeg audio/ogg audio/wav].freeze
+      VIDEO_TYPES = %w[video/mp4 video/ogg video/avi video/quicktime video/webm].freeze
+
+      module_function
+
+      # The ceiling that applies to a given MIME type. Images get a tighter one
+      # than audio and video, and an unknown type is held to the tighter of the
+      # two rather than waved through.
+      def max_bytes_for(mime)
+        image?(mime) ? IMAGE_MAX_BYTES : AUDIO_VIDEO_MAX_BYTES
+      end
+
+      def image?(mime)
+        IMAGE_TYPES.include?(mime.to_s)
+      end
+
+      def within_size?(mime, bytes)
+        bytes.to_i.positive? && bytes.to_i <= max_bytes_for(mime)
+      end
+
+      # Only images can be batched; Meta accepts one audio or video per message.
+      def attachments_within_limit?(count)
+        count.to_i <= ATTACHMENTS_MAX
+      end
+
+      def text_within_limit?(text)
+        text.to_s.bytesize <= TEXT_MAX_BYTES
+      end
+    end
+  end
+end

data/lib/instagram_connect/rate_limiter.rb

@@ -0,0 +1,88 @@
+module InstagramConnect
+  # Keeps calls inside Meta's per-account ceilings.
+  #
+  # Meta publishes several limits at once and exhausting any of them throttles
+  # the whole app for hours, so the cost of being slightly conservative is far
+  # lower than the cost of being slightly wrong.
+  module RateLimiter
+    # Meta's documented per-account limits. The graph default is the floor of
+    # the 4800 × impressions formula: impressions are not knowable from the
+    # messaging API, so the floor is what is safe to assume until the usage
+    # headers say otherwise.
+    BUCKETS = {
+      graph: { limit: 4800, window: 86_400 },
+      conversations: { limit: 2, window: 1 },
+      send_text: { limit: 100, window: 1 },
+      send_media: { limit: 10, window: 1 },
+      private_reply: { limit: 750, window: 3600 },
+      publish: { limit: 50, window: 86_400 }
+    }.freeze
+
+    Outcome = Struct.new(:allowed, :retry_after, keyword_init: true) do
+      def allowed? = allowed
+    end
+
+    module_function
+
+    # Claims one call from a bucket. Returns an Outcome saying whether to
+    # proceed and, if not, how long to wait — callers re-enqueue rather than
+    # sleep, since a worker asleep on a rate limit is a worker not delivering
+    # anything else.
+    def acquire(account:, bucket:, now: Time.current)
+      spec = BUCKETS.fetch(bucket.to_sym)
+      row = budget_for(account, bucket, spec, now)
+
+      return Outcome.new(allowed: false, retry_after: (row.blocked_until - now).ceil) if row.blocked?
+
+      claimed = ApiBudget.where(id: row.id).where("used < limit_value")
+                         .update_all("used = used + 1, updated_at = #{ApiBudget.connection.quote(now)}")
+
+      if claimed == 1
+        Outcome.new(allowed: true, retry_after: nil)
+      else
+        Outcome.new(allowed: false, retry_after: (row.window_end - now).ceil.clamp(1, spec[:window]))
+      end
+    end
+
+    # Records what Meta reported after a call. Its own numbers beat any local
+    # arithmetic, so a warning halves the remaining allowance and a critical
+    # reading blocks the account outright until the stated recovery time.
+    def observe(account:, bucket:, usage:, now: Time.current)
+      return if usage.nil?
+
+      spec = BUCKETS.fetch(bucket.to_sym)
+      row = budget_for(account, bucket, spec, now)
+
+      if usage.critical?
+        row.update!(blocked_until: now + (usage.retry_after || spec[:window]))
+      elsif usage.warning?
+        row.update!(limit_value: [ row.limit_value / 2, row.used + 1 ].max)
+      end
+    end
+
+    # Called when Meta returns an explicit retry_after: one 429 pauses every
+    # job for that account, rather than each one having to discover it.
+    def block!(account:, bucket:, seconds:, now: Time.current)
+      spec = BUCKETS.fetch(bucket.to_sym)
+      budget_for(account, bucket, spec, now).update!(blocked_until: now + seconds.to_i)
+    end
+
+    def budget_for(account, bucket, spec, now)
+      start = window_start(now, spec[:window])
+      ApiBudget.find_or_create_by!(
+        account_id: account.id, bucket: bucket.to_s, window_start: start
+      ) do |row|
+        row.window_seconds = spec[:window]
+        row.limit_value = spec[:limit]
+      end
+    rescue ActiveRecord::RecordNotUnique
+      ApiBudget.find_by!(account_id: account.id, bucket: bucket.to_s, window_start: start)
+    end
+
+    # Fixed windows aligned to the epoch, so every process agrees on where a
+    # window starts without having to coordinate.
+    def window_start(now, seconds)
+      Time.at((now.to_i / seconds) * seconds).utc
+    end
+  end
+end