instagram_connect 0.2.1 → 0.3.1

data/lib/instagram_connect/engine.rb

@@ -43,6 +43,7 @@ module InstagramConnect
     # Encryption configured).
     config.to_prepare do
       InstagramConnect::Account.enable_token_encryption! if InstagramConnect.configuration.encrypt_tokens
+      InstagramConnect::MessageAttachment.enable_file_attachment! if defined?(ActiveStorage::Blob)
     end
   end
 end

data/lib/instagram_connect/ingest/dispatcher.rb

@@ -0,0 +1,151 @@
+require "digest"
+require "json"
+
+module InstagramConnect
+  class Ingest
+    # Walks a verified webhook payload, banks every event it contains on the
+    # ledger, and routes each one to its handler.
+    #
+    # Two rules shape this class:
+    #
+    # 1. Nothing is dropped. An event with no handler, or belonging to no
+    #    connected account, still gets a row. Meta does not re-deliver, so a
+    #    counter increment would be the only record that something was lost.
+    # 2. One bad event cannot poison the batch. Each is wrapped in its own
+    #    rescue and marked `failed` with its error, leaving the rest to process.
+    class Dispatcher
+      def initialize(config)
+        @config = config
+      end
+
+      def call(payload)
+        summary = Summary.new
+        Array(payload && payload["entry"]).each do |entry|
+          process_entry(payload, entry, summary)
+        end
+        summary
+      end
+
+      private
+
+      attr_reader :config
+
+      def process_entry(payload, entry, summary)
+        account = account_for(entry)
+        entry_id = entry["id"].to_s
+        occurred_at = Envelope.time_from(entry["time"])
+
+        flatten(entry).each do |field, event|
+          process_event(
+            account: account, object: payload["object"], field: field, event: event,
+            entry_id: entry_id, entry_time: occurred_at, summary: summary
+          )
+        end
+      end
+
+      # Messaging events arrive under `entry.messaging` whatever subscription
+      # produced them, so their field is recovered by shape. `standby` wraps the
+      # same shapes for a thread this app does not currently control. Changes
+      # (comments, mentions, story insights) name their own field.
+      def flatten(entry)
+        pairs = Array(entry["messaging"]).map { |event| [ Registry.messaging_field_for(event), event ] }
+        pairs += Array(entry["standby"]).map { |event| [ "standby", event ] }
+        pairs + Array(entry["changes"]).map { |change| [ change["field"].to_s, change ] }
+      end
+
+      def process_event(account:, object:, field:, event:, entry_id:, entry_time:, summary:)
+        handler_class = Registry.handler_for(field)
+        key = dedupe_key(handler_class, field, event, entry_id)
+
+        # A handler that needs Meta's id cannot do anything useful without one.
+        # An event like this used to be counted as skipped; banking it means an
+        # operator can see that Meta sent something malformed.
+        if handler_class.respond_to?(:requires_dedupe_key?) && handler_class.requires_dedupe_key? &&
+           handler_class.dedupe_key(event).blank?
+          record_unhandled(account, object, field, event, entry_id, entry_time, key, summary)
+          return
+        end
+
+        record = WebhookEvent.claim(
+          account: account, object: object, field: field,
+          event_type: field, dedupe_key: key, entry_id: entry_id,
+          occurred_at: event_time(event) || entry_time, payload: event,
+          handler: handler_class.name
+        )
+
+        if record.nil?
+          summary.duplicates += 1
+          return
+        end
+
+        if account.nil? || !Registry.handled?(field)
+          record.mark_unhandled!
+          summary.unhandled += 1
+          return
+        end
+
+        run(handler_class, record, account, object, field, event, entry_id, entry_time, summary)
+      end
+
+      def run(handler_class, record, account, object, field, event, entry_id, entry_time, summary)
+        envelope = Envelope.new(
+          account: account, object: object, field: field, event_type: field,
+          event: event, entry_id: entry_id,
+          occurred_at: event_time(event) || entry_time, config: config
+        )
+        handler = handler_class.new(envelope)
+        subject = handler.call
+        record.mark_processed!(subject)
+        summary.count(field)
+        deliver(handler.notification, summary)
+      rescue StandardError => e
+        record.mark_failed!(e)
+        summary.failed += 1
+      end
+
+      # The host callback runs outside the handler, in its own rescue. The rows
+      # are already committed at this point, so a host hook raising must not
+      # flip the event to failed — it would be replayed and duplicate the data.
+      def deliver(notification, summary)
+        return if notification.nil?
+
+        handler, argument = notification
+        handler.call(argument) if handler.respond_to?(:call)
+      rescue StandardError => e
+        summary.callback_errors += 1
+        config.logger&.error("[InstagramConnect] host callback raised: #{e.class}: #{e.message}")
+      end
+
+      def record_unhandled(account, object, field, event, entry_id, entry_time, key, summary)
+        record = WebhookEvent.claim(
+          account: account, object: object, field: field, event_type: field,
+          dedupe_key: key, entry_id: entry_id,
+          occurred_at: event_time(event) || entry_time, payload: event,
+          handler: Handlers::Unknown.name
+        )
+        if record.nil?
+          summary.duplicates += 1
+        else
+          record.mark_unhandled!
+          summary.unhandled += 1
+        end
+      end
+
+      def dedupe_key(handler_class, field, event, entry_id)
+        handler_class.dedupe_key(event).presence ||
+          Digest::SHA256.hexdigest("#{field}:#{entry_id}:#{JSON.generate(event)}")
+      end
+
+      def event_time(event)
+        Envelope.time_from(event["timestamp"])
+      end
+
+      def account_for(entry)
+        id = entry["id"].to_s
+        return nil if id.empty?
+
+        Account.find_by(ig_user_id: id) || Account.find_by(page_id: id)
+      end
+    end
+  end
+end

data/lib/instagram_connect/ingest/envelope.rb

@@ -0,0 +1,31 @@
+module InstagramConnect
+  class Ingest
+    # One webhook event, plus the context needed to interpret it: which account
+    # it belongs to, which field Meta delivered it under, and when it actually
+    # happened on the wire (as opposed to when we got round to storing it).
+    Envelope = Struct.new(
+      :account, :object, :field, :event_type, :event, :entry_id, :occurred_at, :config,
+      keyword_init: true
+    ) do
+      # Anything outside this is not a timestamp Meta could have sent, and
+      # storing it would corrupt every ordering that reads occurred_at.
+      MAX_SECONDS = 4_102_444_800 # 2100-01-01
+
+      # Meta timestamps are milliseconds since the epoch. Ordering off this
+      # rather than our own created_at is what stops a delayed webhook batch
+      # silently reordering a conversation.
+      def self.time_from(millis)
+        return nil if millis.nil?
+
+        seconds = millis.to_i / 1000.0
+        return nil unless seconds.finite? && seconds >= 0 && seconds <= MAX_SECONDS
+
+        Time.at(seconds).utc
+      end
+
+      def dig(*keys)
+        event.dig(*keys)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+module InstagramConnect
+  class Ingest
+    module Handlers
+      # A handler turns one webhook event into persisted rows and returns the
+      # row it produced (or nil), which the dispatcher records on the ledger so
+      # an operator can trace an event to its result.
+      #
+      # Subclasses implement `.dedupe_key` and `#call`.
+      class Base
+        # Meta's own identifier for this event, used as the dedupe claim. Nil
+        # means the event carries no stable id and the dispatcher falls back to
+        # hashing the payload.
+        def self.dedupe_key(_event)
+          nil
+        end
+
+        # The host callback this handler wants fired, and its argument. Read by
+        # the dispatcher *after* `#call` returns, so the callback runs outside
+        # the handler in its own rescue: a host hook must never roll back an
+        # ingest whose data is already stored.
+        attr_reader :notification
+
+        def initialize(envelope)
+          @envelope = envelope
+          @notification = nil
+        end
+
+        def call
+          raise NotImplementedError
+        end
+
+        private
+
+        attr_reader :envelope
+
+        def account
+          envelope.account
+        end
+
+        def event
+          envelope.event
+        end
+
+        def config
+          envelope.config
+        end
+
+        def notify(handler, argument)
+          @notification = [ handler, argument ]
+          argument
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+module InstagramConnect
+  class Ingest
+    module Handlers
+      # A comment on the account's own media. Also covers `live_comments`,
+      # which carry the same shape — the difference is that a private reply to
+      # a live comment is only valid while the broadcast is running.
+      class Comments < Base
+        def self.dedupe_key(event)
+          event.dig("value", "id").presence
+        end
+
+        def self.requires_dedupe_key?
+          true
+        end
+
+        def call
+          comment = InstagramConnect::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"]
+          )
+          comment.update!(
+            from_ig_id: value.dig("from", "id"),
+            commented_at: commented_at,
+            # A private reply to a live comment is only valid while the
+            # broadcast is running, so which field delivered this decides
+            # whether that action can be offered at all.
+            is_live: envelope.field == "live_comments"
+          )
+
+          record_media(comment)
+          notify(config.on_comment, comment)
+          comment
+        end
+
+        private
+
+        def value
+          event["value"] || {}
+        end
+
+        def commented_at
+          envelope.occurred_at || Time.current
+        end
+
+        # The comment names a media we may never have seen — it could predate
+        # this install, or have been posted from a phone.
+        def record_media(comment)
+          return if comment.media_id.blank?
+
+          InstagramConnect::MediaItem.record(account: account, ig_media_id: comment.media_id)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+module InstagramConnect
+  class Ingest
+    module Handlers
+      # Someone @mentioned the account, in a comment or in a caption.
+      #
+      # Meta does not store these notifications and never re-delivers them, so
+      # this handler is the single point at which the event either becomes a row
+      # or ceases to exist. Nothing here is allowed to be best-effort.
+      class Mentions < Base
+        def self.dedupe_key(event)
+          value = event["value"] || {}
+          media = value["media_id"].presence
+          return nil if media.nil?
+
+          "#{media}:#{value['comment_id'].presence || 'caption'}"
+        end
+
+        def self.requires_dedupe_key?
+          true
+        end
+
+        def call
+          InstagramConnect::MediaItem.record(account: account, ig_media_id: value["media_id"])
+
+          InstagramConnect::Mention.record(
+            account: account,
+            kind: value["comment_id"].present? ? "comment" : "caption",
+            ig_media_id: value["media_id"],
+            comment_id: value["comment_id"],
+            text: value["text"],
+            from_username: value.dig("from", "username"),
+            mentioned_at: mentioned_at
+          )
+        end
+
+        private
+
+        def value
+          event["value"] || {}
+        end
+
+        def mentioned_at
+          envelope.occurred_at || Time.current
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+module InstagramConnect
+  class Ingest
+    module Handlers
+      # A customer reacting to (or un-reacting from) a message.
+      #
+      # Reactions also reopen the 24-hour messaging window, which is why they
+      # bump the conversation's activity even though they are not messages.
+      class MessageReactions < Base
+        # A customer can react, unreact, then react again with the same emoji on
+        # the same message. Those are three real events sharing a mid, so the
+        # action and the wire timestamp both belong in the key. A genuine
+        # redelivery repeats the timestamp and still collapses, which is the
+        # distinction that matters.
+        def self.dedupe_key(event)
+          reaction = event["reaction"] || {}
+          mid = reaction["mid"].presence or return nil
+
+          [ mid, reaction["action"], reaction["reaction"], event["timestamp"] ].compact.join(":")
+        end
+
+        def call
+          record = InstagramConnect::MessageReaction.create!(
+            conversation: conversation,
+            message: message,
+            ig_message_id: mid,
+            igsid: igsid,
+            actor: actor,
+            action: action,
+            reaction: payload["reaction"],
+            emoji: payload["emoji"],
+            reacted_at: reacted_at
+          )
+          refresh_message_projection
+          conversation.register_event(reacted_at)
+          record
+        end
+
+        private
+
+        def payload
+          event["reaction"] || {}
+        end
+
+        def mid
+          payload["mid"].to_s
+        end
+
+        def action
+          payload["action"] == "unreact" ? "unreact" : "react"
+        end
+
+        # A reaction the business left shows up as an event from the account
+        # itself rather than from the customer.
+        def actor
+          igsid == account.ig_user_id ? "business" : "customer"
+        end
+
+        def igsid
+          event.dig("sender", "id").to_s
+        end
+
+        def reacted_at
+          envelope.occurred_at || Time.current
+        end
+
+        def message
+          @message ||= InstagramConnect::Message.find_by(ig_message_id: mid)
+        end
+
+        def conversation
+          @conversation ||= message&.conversation ||
+            InstagramConnect::Conversation.locate(account: account, igsid: igsid)
+        end
+
+        # Denormalized onto the message so a bubble renders without a join.
+        # Recomputed from the log rather than incremented, so an out-of-order
+        # unreact cannot leave the projection disagreeing with its source.
+        def refresh_message_projection
+          return if message.nil?
+
+          current = InstagramConnect::MessageReaction.current_for(mid)
+          InstagramConnect::Message.where(id: message.id).update_all(
+            reactions_count: InstagramConnect::MessageReaction.where(ig_message_id: mid, action: "react").count,
+            last_reaction: current&.reaction,
+            updated_at: Time.current
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,135 @@
+module InstagramConnect
+  class Ingest
+    module Handlers
+      # Inbound DMs, and echoes of messages the business sent from anywhere —
+      # this app, the Instagram app, or Meta Business Suite.
+      class Messages < Base
+        def self.dedupe_key(event)
+          event.dig("message", "mid").presence
+        end
+
+        # Without Meta's mid there is no way to dedupe this message against its
+        # own echo, so it is banked unparsed rather than stored twice.
+        def self.requires_dedupe_key?
+          true
+        end
+
+        def call
+          message = InstagramConnect::Message.create!(
+            conversation: conversation,
+            direction: echo? ? "outbound" : "inbound",
+            status: echo? ? "sent" : "received",
+            source: echo? ? "operator_app" : "inbound",
+            kind: "dm",
+            body: payload["text"],
+            ig_message_id: mid,
+            media_status: media_status,
+            media_kind: attachments.first&.dig("type"),
+            sent_at: envelope.occurred_at,
+            deleted_at: payload["is_deleted"] ? (envelope.occurred_at || Time.current) : nil,
+            unsupported: payload["is_unsupported"] ? true : false,
+            reply_to_mid: payload.dig("reply_to", "mid"),
+            quick_reply_payload: payload.dig("quick_reply", "payload"),
+            referral_ref: payload.dig("referral", "ref"),
+            referral_source: payload.dig("referral", "source"),
+            referral_type: payload.dig("referral", "type"),
+            referral_product_id: payload.dig("referral", "product", "id"),
+            story_id: story&.dig("id"),
+            story_url: story&.dig("url")
+          )
+          store_attachments(message)
+          conversation.register_message(message)
+          record_legacy_claim
+
+          # An echo is our own outbound message coming back; firing on_message
+          # for it would have the host reply to itself.
+          notify(config.on_message, message) unless echo?
+          message
+        end
+
+        private
+
+        def payload
+          event["message"] || {}
+        end
+
+        def mid
+          payload["mid"].to_s
+        end
+
+        def echo?
+          payload["is_echo"] ? true : false
+        end
+
+        def attachments
+          Array(payload["attachments"])
+        end
+
+        # An unsupported message has nothing fetchable behind it, and Instagram
+        # CDN links expire with no way to ask again — so the verdict is decided
+        # here, before the insert, and the row is born in its final state.
+        def media_status
+          return "unavailable" if payload["is_unsupported"]
+
+          attachments.any? { |a| a.dig("payload", "url").present? } ? "pending" : "none"
+        end
+
+        # Rows are written in one insert_all so the bubble is born in its final
+        # state: one create, one broadcast, no flicker as files resolve. Each
+        # fetch is its own job, so a ten-image message does not serialise
+        # behind whichever file is slowest.
+        def store_attachments(message)
+          return if attachments.empty?
+
+          rows = attachments.each_with_index.map do |attachment, index|
+            url = attachment.dig("payload", "url")
+            {
+              message_id: message.id, position: index,
+              kind: attachment["type"].presence || "file",
+              source_url: url,
+              state: url.present? ? "pending" : "skipped",
+              created_at: Time.current, updated_at: Time.current
+            }
+          end
+          InstagramConnect::MessageAttachment.insert_all(rows)
+
+          message.attachments.reload.select(&:fetchable?).each do |attachment|
+            InstagramConnect::FetchMediaJob.perform_later(attachment.id)
+          end
+        end
+
+        # A story reply and a story mention both point at the story they came
+        # from; Meta nests it under the attachment payload.
+        def story
+          @story ||= attachments.filter_map { |a| a.dig("payload", "story") }.first
+        end
+
+        # On an echo the customer is the recipient; on an inbound message they
+        # are the sender. Either way the conversation is keyed by their IGSID.
+        def igsid
+          (echo? ? event.dig("recipient", "id") : event.dig("sender", "id")).to_s
+        end
+
+        def conversation
+          @conversation ||= InstagramConnect::Conversation.locate(account: account, igsid: igsid).tap do |thread|
+            # Meta sends the profile on a separate call from the message, so a
+            # thread starts life knowing only an opaque id. Fetch it once, when
+            # the thread first appears, rather than on every message.
+            enqueue_profile_sync(thread) if thread.profile_synced_at.nil?
+          end
+        end
+
+        def enqueue_profile_sync(thread)
+          InstagramConnect::ProfileSyncJob.perform_later(conversation_id: thread.id)
+        end
+
+        # The webhook ledger is the dedupe claim now. InboundMessage is kept in
+        # step so a host querying it against 0.2.x behaviour still sees every
+        # message; it is deprecated and will go at 1.0.
+        def record_legacy_claim
+          InstagramConnect::InboundMessage.claim(ig_message_id: mid, account_id: account.id)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+module InstagramConnect
+  class Ingest
+    module Handlers
+      # Thread control moving between apps — typically between this app and the
+      # Page Inbox a human operator uses.
+      #
+      # This matters beyond bookkeeping: the Send API rejects a message on a
+      # thread another app owns, so a send has to read thread_owner_app_id
+      # first rather than discovering it as an opaque API error.
+      class MessagingHandover < Base
+        CONTROL_KEYS = %w[pass_thread_control take_thread_control request_thread_control].freeze
+
+        def self.dedupe_key(event)
+          sender = event.dig("sender", "id")
+          key = CONTROL_KEYS.find { |k| event[k] }
+          return nil if key.nil?
+
+          [ sender, event["timestamp"], key, event.dig(key, "new_owner_app_id") ].compact.join(":")
+        end
+
+        def call
+          conversation.register_thread_control(owner_app_id: new_owner_app_id, at: handed_over_at)
+          conversation
+        end
+
+        private
+
+        def control_key
+          @control_key ||= CONTROL_KEYS.find { |key| event[key] }
+        end
+
+        # A pass names the app receiving control. A take is the Page Inbox
+        # seizing it, so control lands with Meta's own app rather than a named
+        # one; recording nil is honest — we know we no longer own the thread.
+        def new_owner_app_id
+          event.dig(control_key.to_s, "new_owner_app_id")
+        end
+
+        def igsid
+          event.dig("sender", "id").to_s
+        end
+
+        def handed_over_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_optins.rb

@@ -0,0 +1,37 @@
+module InstagramConnect
+  class Ingest
+    module Handlers
+      # The customer opted in to notification messages. There is nothing to
+      # store on the thread beyond the fact that they interacted — the opt-in
+      # token itself lives in the banked event, where a host that implements
+      # recurring notifications can read it without the gem taking a position
+      # on how that should work.
+      class MessagingOptins < Base
+        def self.dedupe_key(event)
+          sender = event.dig("sender", "id").presence or return nil
+
+          "#{sender}:#{event['timestamp']}"
+        end
+
+        def call
+          conversation.register_event(opted_in_at)
+          conversation
+        end
+
+        private
+
+        def igsid
+          event.dig("sender", "id").to_s
+        end
+
+        def opted_in_at
+          envelope.occurred_at || Time.current
+        end
+
+        def conversation
+          @conversation ||= InstagramConnect::Conversation.locate(account: account, igsid: igsid)
+        end
+      end
+    end
+  end
+end