instagram_connect 0.2.0 → 0.3.0

data/lib/instagram_connect/client.rb

@@ -33,6 +33,61 @@ module InstagramConnect
       })
     end
 
+    # Typing indicators and read receipts. Meta is explicit that a sender action
+    # request must carry ONLY the recipient and the action — bundling it with a
+    # message silently drops one of the two.
+    def send_sender_action(recipient_id:, action:)
+      post("/me/messages", { recipient: { id: recipient_id }, sender_action: action })
+    end
+
+    def send_quick_replies(recipient_id:, text:, replies:, tag: nil)
+      quick_replies = Array(replies).map do |reply|
+        { content_type: "text", title: reply[:title].to_s[0, 20], payload: reply[:payload].to_s }
+      end
+      send_message(recipient: { id: recipient_id },
+                   message: { text: text, quick_replies: quick_replies }, tag: tag)
+    end
+
+    def send_attachment(recipient_id:, attachment_id:, tag: nil)
+      send_message(recipient: { id: recipient_id },
+                   message: { attachment: { payload: { attachment_id: attachment_id } } }, tag: tag)
+    end
+
+    # Uploads bytes to Meta and returns a reusable attachment id.
+    #
+    # Preferred over handing Meta a signed URL to the host's storage: a signed
+    # URL is a bearer capability for a customer's file, sitting on the public
+    # internet for as long as its TTL, fetched from an address we do not
+    # control. This moves the bytes over an authenticated POST instead, and the
+    # returned id can be reused rather than re-uploading the same file.
+    # +file+ must be a File or Tempfile — HTTParty builds the multipart body
+    # from objects that expose a path, which is also what ActiveStorage's
+    # blob.open yields.
+    def upload_attachment(file:, type: "image")
+      body = {
+        platform: "instagram",
+        message: { attachment: { type: type, payload: { is_reusable: true } } }.to_json,
+        filedata: file
+      }
+      post_multipart("/me/message_attachments", body)
+    end
+
+    # Ice breakers and the persistent menu both live on the messenger profile.
+    def set_messenger_profile(**fields)
+      post("/me/messenger_profile", fields.merge(platform: "instagram"))
+    end
+
+    def messenger_profile(fields:)
+      get("/me/messenger_profile", { fields: Array(fields).join(","), platform: "instagram" })
+    end
+
+    def delete_messenger_profile(fields:)
+      parse(HTTParty.delete(url("/me/messenger_profile"),
+                            headers: bearer.merge("Content-Type" => "application/json"),
+                            body: { fields: Array(fields), platform: "instagram" }.to_json,
+                            timeout: TIMEOUT))
+    end
+
     # One-time private reply to a comment (comment -> DM), valid 7 days.
     def private_reply(comment_id:, text:)
       post("/me/messages", { recipient: { comment_id: comment_id }, message: { text: text } })
@@ -85,6 +140,13 @@ module InstagramConnect
       get("/#{media_id}/insights", { metric: Array(metrics).join(",") })
     end
 
+    # The connected account's own profile. A different call from #profile,
+    # which looks up the person on the other end of a thread.
+    def account_profile(ig_user_id: @ig_user_id, fields: %w[username name profile_picture_url
+                                                            followers_count media_count])
+      get("/#{require_ig_user_id(ig_user_id)}", { fields: Array(fields).join(",") })
+    end
+
     def profile(igsid:, fields: %w[name username profile_pic])
       get("/#{igsid}", { fields: Array(fields).join(",") })
     end
@@ -95,6 +157,38 @@ module InstagramConnect
       get("/me/accounts", { fields: "id,name,access_token,instagram_business_account" })
     end
 
+    # Walks a Graph collection to the end, following Meta's own cursors.
+    #
+    # Offsets are not safe here: a collection can shift between calls, so an
+    # offset silently skips or repeats rows. +limit_pages+ exists because these
+    # collections can be unbounded and every page spends rate budget.
+    def each_page(path, query = {}, limit_pages: 25)
+      cursor = nil
+      pages = 0
+
+      while pages < limit_pages
+        page_query = cursor ? query.merge(after: cursor) : query
+        result = get(path, page_query)
+        return result unless result.success?
+
+        yield result
+        pages += 1
+        cursor = result.next_cursor
+        break if cursor.nil?
+      end
+
+      Result.ok(data: { "pages" => pages })
+    end
+
+    # Every record across every page, for callers that just want the list.
+    def collect(path, query = {}, limit_pages: 25)
+      records = []
+      result = each_page(path, query, limit_pages: limit_pages) { |page| records.concat(page.records) }
+      return result if result.failure?
+
+      Result.ok(data: { "data" => records })
+    end
+
     def fetch_media_binary(url:)
       response = HTTParty.get(url, headers: bearer, timeout: TIMEOUT, follow_redirects: true)
       unless response.success?
@@ -135,6 +229,13 @@ module InstagramConnect
       parse(HTTParty.delete(url(path), headers: bearer, timeout: TIMEOUT))
     end
 
+    # multipart/form-data rather than JSON. The Attachment Upload API takes raw
+    # bytes, which a JSON body cannot carry.
+    def post_multipart(path, body)
+      parse(HTTParty.post(url(path), headers: bearer, body: body,
+                          multipart: true, timeout: TIMEOUT))
+    end
+
     def url(path)
       "#{strategy.graph_host}/#{config.graph_version}#{path}"
     end
@@ -146,14 +247,19 @@ module InstagramConnect
     def parse(response)
       data = response.parsed_response
       data = {} unless data.is_a?(Hash)
+      usage = Usage.from_headers(response.headers)
       if response.success?
-        Result.ok(id: data["message_id"] || data["id"], data: data)
+        Result.ok(id: data["message_id"] || data["id"], data: data, usage: usage)
       else
         err = data["error"].is_a?(Hash) ? data["error"] : {}
         Result.error(err["message"] || "HTTP #{response.code}",
                      error_code: err["code"],
-                     retry_after: err.dig("error_data", "retry_after"),
-                     data: data)
+                     # Meta names the wait in the error when it has one; when it
+                     # does not, the usage header's estimate is the next best
+                     # thing and is better than an invented backoff.
+                     retry_after: err.dig("error_data", "retry_after") || usage&.retry_after,
+                     data: data,
+                     usage: usage)
       end
     end
   end

data/lib/instagram_connect/configuration.rb

@@ -41,6 +41,16 @@ module InstagramConnect
     attr_reader :auth_path
     attr_writer :theme
 
+    # A copy of this configuration pinned to one auth path. Accounts store the
+    # path they were connected with, and a host can have both — so the global
+    # setting is the default for *new* connections, never an override on an
+    # existing one.
+    def for_auth_path(path)
+      return self if path.blank? || path.to_sym == auth_path
+
+      dup.tap { |copy| copy.auth_path = path }
+    end
+
     def initialize
       @auth_path = (ENV["INSTAGRAM_CONNECT_AUTH_PATH"] || "instagram_login").to_sym
       @app_id = ENV["INSTAGRAM_CONNECT_APP_ID"] || ENV["INSTAGRAM_APP_ID"]

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