instagram_connect 0.2.0 → 0.3.0

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

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