instagram_connect 0.2.1 → 0.3.0

data/app/jobs/instagram_connect/account_readiness_job.rb

@@ -0,0 +1,148 @@
+require "httparty"
+
+module InstagramConnect
+  # Closes the gap between "an operator clicked Connect" and "events actually
+  # flow", then keeps it closed.
+  #
+  # Two things stand in that gap and neither has a dashboard equivalent:
+  #
+  #   1. TOKEN GRADE. The OAuth exchange returns a long-lived *user* token, but
+  #      every Instagram messaging call and the subscription below are Page
+  #      token operations. This swaps in the Page token. Page tokens minted from
+  #      a long-lived user token do not expire, so the expiry is cleared with it.
+  #   2. PAGE SUBSCRIPTION. Ticking webhook fields in the app dashboard
+  #      subscribes the *app*. Meta delivers nothing until the *Page* lists the
+  #      app in its subscribed_apps, which is a per-Page Graph call.
+  #
+  # Both steps read before they write, so a scheduled run costs two GETs and
+  # changes nothing once an account is healthy. That is the point: a token Meta
+  # rotates, or a subscription dropped when an app moves between Development and
+  # Live mode, heals itself rather than becoming a console command nobody
+  # remembers to run.
+  #
+  # This lives in the gem rather than in a host because the field list has to
+  # track what Ingest can actually parse. Maintained separately, the two drift
+  # and the host silently receives events it drops.
+  class AccountReadinessJob < ApplicationJob
+    queue_as :default
+
+    HTTP_TIMEOUT = 15
+
+    def self.subscribed_fields
+      Ingest::Registry.subscribable_fields
+    end
+
+    # Cheap negative check so an install with no connected account never
+    # enqueues anything.
+    def self.enqueue_if_needed
+      return :nothing_to_do if InstagramConnect.configuration.app_id.blank?
+      return :nothing_to_do unless connectable.exists?
+
+      perform_later
+      :enqueued
+    end
+
+    def self.connectable
+      Account.active.where.not(page_id: [ nil, "" ])
+    end
+
+    def perform
+      return if InstagramConnect.configuration.app_id.blank?
+
+      self.class.connectable.find_each do |account|
+        # Cleared up front rather than on success, so a step that records a soft
+        # failure (no Page token, say) is not immediately wiped by the same pass
+        # completing without raising.
+        account.update_columns(readiness_error: nil) if account.readiness_error.present?
+
+        ensure_page_token(account)
+        ensure_subscription(account)
+      rescue StandardError => e
+        # One unhealthy account must not stop the rest, and the next run retries
+        # anyway. The reason is kept on the row so a health screen can show it.
+        account.update_columns(readiness_error: "#{e.class}: #{e.message}".truncate(255))
+        logger&.error("[InstagramConnect] readiness failed for account=#{account.id}: #{e.message}")
+      end
+    end
+
+    private
+
+    def logger
+      InstagramConnect.configuration.logger
+    end
+
+    # A Page token's /me is the Page itself; a user token's /me is the person.
+    # That one field is the cheapest way to tell which grade we are holding.
+    def ensure_page_token(account)
+      return if account.page_access_token.present? && account.page_token_verified_at.present?
+
+      identity = graph_get(account, "/me", fields: "id")
+
+      # Already holding a Page token — which is the state a host arrives in if
+      # it swapped the token itself before this job existed. /me/accounts cannot
+      # be called with a Page token, so the token cannot be re-derived; adopt
+      # what is there rather than attempting a recovery that cannot work.
+      if identity["id"].to_s == account.page_id.to_s
+        account.update!(page_access_token: account.api_token, page_token_verified_at: Time.current)
+        return
+      end
+
+      pages = graph_get(account, "/me/accounts", fields: "id,access_token")
+      page = Array(pages["data"]).find { |p| p["id"].to_s == account.page_id.to_s }
+
+      if page.nil? || page["access_token"].blank?
+        account.update!(needs_reconnect: true,
+                        readiness_error: "no Page token for page=#{account.page_id}")
+        return
+      end
+
+      account.update!(page_access_token: page["access_token"], page_token_verified_at: Time.current,
+                      token_expires_at: nil, needs_reconnect: false)
+    end
+
+    def ensure_subscription(account)
+      return if account.page_access_token.blank?
+
+      wanted = self.class.subscribed_fields
+      current = graph_get(account, "/#{account.page_id}/subscribed_apps", fields: "subscribed_fields")
+      subscribed = Array(current["data"]).flat_map { |app| Array(app["subscribed_fields"]) }.map(&:to_s)
+
+      if (wanted - subscribed).empty?
+        account.update!(subscribed_fields: subscribed.join(","), subscriptions_synced_at: Time.current)
+        return
+      end
+
+      graph_post(account, "/#{account.page_id}/subscribed_apps", subscribed_fields: wanted.join(","))
+      account.update!(subscribed_fields: wanted.join(","), subscriptions_synced_at: Time.current)
+    end
+
+    def graph_get(account, path, **query)
+      parse(HTTParty.get(url(account, path), headers: bearer(account), query: query,
+                         timeout: HTTP_TIMEOUT), path)
+    end
+
+    def graph_post(account, path, **body)
+      parse(HTTParty.post(url(account, path), headers: bearer(account), body: body,
+                          timeout: HTTP_TIMEOUT), path)
+    end
+
+    # Host and version come from the account's own strategy, so this can never
+    # drift onto a different Graph version than the client's calls.
+    def url(account, path)
+      config = InstagramConnect.configuration.for_auth_path(account.auth_path)
+      "#{Auth.for(config).graph_host}/#{config.graph_version}#{path}"
+    end
+
+    def bearer(account)
+      { "Authorization" => "Bearer #{account.api_token}" }
+    end
+
+    def parse(response, path)
+      body = response.parsed_response
+      body = {} unless body.is_a?(Hash)
+      raise "Graph #{path} failed: HTTP #{response.code} #{body.dig('error', 'message')}" unless response.success?
+
+      body
+    end
+  end
+end

data/app/jobs/instagram_connect/fetch_media_job.rb

@@ -0,0 +1,110 @@
+require "httparty"
+
+module InstagramConnect
+  # Copies one inbound attachment's bytes out of Meta's CDN and into the host's
+  # own storage.
+  #
+  # This runs against a clock nobody controls: Instagram's media URLs expire and
+  # there is no endpoint to ask for a fresh one. So a failure here is permanent
+  # for that file, which is why the retry ladder ends in a terminal state rather
+  # than leaving the row pending — a pending attachment renders as a loading
+  # placeholder, and one that never resolves is worse than an honest "this file
+  # is no longer available".
+  class FetchMediaJob < ApplicationJob
+    queue_as :default
+
+    TIMEOUT = 30
+    TRANSPORT_ERRORS = [
+      Errno::ECONNRESET, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ETIMEDOUT,
+      Net::OpenTimeout, Net::ReadTimeout, SocketError, IOError
+    ].freeze
+
+    retry_on(*TRANSPORT_ERRORS, attempts: 3, wait: :polynomially_longer) do |job, error|
+      exhausted(job.arguments.first, error)
+    end
+
+    # Retries are spent. Without this the job would land in the dead set and
+    # leave the attachment pending for ever — a loading placeholder in the
+    # thread that nothing will ever resolve.
+    def self.exhausted(attachment_id, error)
+      MessageAttachment.find_by(id: attachment_id)&.mark_unavailable!("transport:#{error.class}")
+    end
+
+    def perform(attachment_id)
+      attachment = MessageAttachment.find_by(id: attachment_id)
+      return if attachment.nil?
+      return unless storage_available?
+
+      # The guard and the write have to be one atomic step: two deliveries of
+      # the same webhook would otherwise both see "pending" and both fetch.
+      attachment.with_lock do
+        next unless attachment.fetchable?
+
+        fetch_into(attachment)
+      end
+    end
+
+    private
+
+    def fetch_into(attachment)
+      response = HTTParty.get(attachment.source_url, timeout: TIMEOUT, follow_redirects: true)
+      unless response.success?
+        # An expired CDN link is the common case and no amount of retrying
+        # fixes it, so this is terminal rather than raised.
+        attachment.mark_unavailable!("http_#{response.code}")
+        return
+      end
+
+      verdict = Media::Attaching.evaluate(
+        body: response.body,
+        declared_mime: response.headers["content-type"],
+        filename: attachment.filename
+      )
+
+      if verdict.ok?
+        store(attachment, response.body, verdict)
+      else
+        attachment.mark_unavailable!(verdict.error)
+      end
+    ensure
+      refresh_message_media_status(attachment)
+    end
+
+    def store(attachment, body, verdict)
+      attachment.file.attach(
+        io: StringIO.new(body),
+        filename: attachment.filename.presence || default_filename(attachment, verdict.mime),
+        content_type: verdict.mime
+      )
+      attachment.mark_attached!(mime: verdict.mime, size: verdict.size)
+    end
+
+    def default_filename(attachment, mime)
+      extension = Rack::Mime::MIME_TYPES.invert[mime] || ""
+      "instagram-#{attachment.id}#{extension}"
+    end
+
+    # The message carries the aggregate verdict across its attachments, so the
+    # thread can show one state per bubble rather than one per file.
+    def refresh_message_media_status(attachment)
+      message = attachment.message
+      return if message.nil?
+
+      states = message.attachments.reload.pluck(:state)
+      status = if states.include?("pending") then "pending"
+      elsif states.any? { |s| s == "attached" } then "attached"
+      elsif states.empty? then "none"
+      else "unavailable"
+      end
+
+      Message.where(id: message.id).update_all(media_status: status, updated_at: Time.current)
+      message.broadcast_refresh
+    end
+
+    # A host without Active Storage still receives messages; it simply keeps the
+    # attachment rows as metadata and never fetches bytes.
+    def storage_available?
+      defined?(ActiveStorage::Blob).present?
+    end
+  end
+end

data/app/jobs/instagram_connect/profile_sync_job.rb

@@ -0,0 +1,78 @@
+module InstagramConnect
+  # Fills in who people actually are.
+  #
+  # The columns for this have existed since 0.1 and nothing ever wrote them, so
+  # an inbox showed a 17-digit Instagram-scoped id where a handle belongs and an
+  # account showed nothing at all. Meta returns profile data on a separate call
+  # from the message, so it has to be fetched deliberately.
+  #
+  # Re-syncing is rate-limited by RESYNC_AFTER rather than by cleverness: a
+  # display name changes rarely, and every refetch spends budget that inbound
+  # message handling needs more.
+  class ProfileSyncJob < ApplicationJob
+    queue_as :default
+
+    RESYNC_AFTER = 7.days
+
+    def perform(account_id: nil, conversation_id: nil)
+      if conversation_id
+        sync_conversation(Conversation.find_by(id: conversation_id))
+      elsif account_id
+        sync_account(Account.find_by(id: account_id))
+      else
+        Account.active.find_each { |account| sync_account(account) }
+      end
+    end
+
+    private
+
+    def sync_account(account)
+      return if account.nil? || fresh?(account.profile_synced_at)
+
+      result = account.client.account_profile
+      return record_failure(account, result) unless result.success?
+
+      data = result.data
+      account.update!(
+        username: data["username"].presence || account.username,
+        name: data["name"].presence || account.name,
+        profile_picture_url: data["profile_picture_url"],
+        followers_count: data["followers_count"],
+        media_count: data["media_count"],
+        profile_synced_at: Time.current
+      )
+    end
+
+    def sync_conversation(conversation)
+      return if conversation.nil? || fresh?(conversation.profile_synced_at)
+
+      result = conversation.account.client.profile(igsid: conversation.igsid)
+
+      # A customer who blocked the business, or deleted their account, cannot be
+      # looked up. Stamping the attempt stops the job retrying them on every
+      # message they ever sent.
+      unless result.success?
+        conversation.update_columns(profile_synced_at: Time.current)
+        return
+      end
+
+      data = result.data
+      conversation.update!(
+        username: data["username"].presence || conversation.username,
+        display_name: data["name"].presence || conversation.display_name,
+        profile_picture_url: data["profile_pic"] || data["profile_picture_url"],
+        profile_synced_at: Time.current
+      )
+    end
+
+    def fresh?(synced_at)
+      synced_at.present? && synced_at > RESYNC_AFTER.ago
+    end
+
+    def record_failure(account, result)
+      InstagramConnect.configuration.logger&.warn(
+        "[InstagramConnect] profile sync failed for account=#{account.id}: #{result.error_message}"
+      )
+    end
+  end
+end

data/app/jobs/instagram_connect/replay_events_job.rb

@@ -0,0 +1,57 @@
+module InstagramConnect
+  # Re-runs banked webhook events through the current handlers.
+  #
+  # This is the payoff for storing raw payloads. Two situations need it, and
+  # neither is recoverable any other way, because Meta does not re-deliver:
+  #
+  #   - A field was subscribed before the gem could parse it. Its events banked
+  #     as `unhandled`; once the handler ships, replay them and the history is
+  #     complete rather than starting from the deploy.
+  #   - A handler had a bug. The events are marked `failed` with the error;
+  #     fix the bug, replay, and no data was lost in between.
+  #
+  # Replaying is safe to repeat: handlers write through the same upserts and
+  # unique indexes the live path uses.
+  class ReplayEventsJob < ApplicationJob
+    queue_as :default
+
+    def perform(field: nil, since: nil, limit: 500, config: nil)
+      configuration = config || InstagramConnect.configuration
+
+      scope = WebhookEvent.replayable.chronological.limit(limit)
+      scope = scope.for_field(field) if field.present?
+      scope = scope.where(created_at: since..) if since.present?
+
+      scope.find_each do |event|
+        replay(event, configuration)
+      end
+    end
+
+    private
+
+    def replay(event, configuration)
+      handler_class = Ingest::Registry.handler_for(event.field)
+      unless Ingest::Registry.handled?(event.field) && event.account
+        # Still nothing that can parse it — leave the row banked rather than
+        # burning through the same backlog on every run.
+        return
+      end
+
+      envelope = Ingest::Envelope.new(
+        account: event.account, object: event.object, field: event.field,
+        event_type: event.event_type, event: event.payload, entry_id: event.entry_id,
+        occurred_at: event.occurred_at, config: configuration
+      )
+      handler = handler_class.new(envelope)
+      event.increment!(:attempts)
+      subject = handler.call
+      event.mark_processed!(subject)
+    rescue StandardError => e
+      event.mark_failed!(e)
+      configuration.logger&.error(
+        "[InstagramConnect] replay failed for event=#{event.id} field=#{event.field}: " \
+        "#{e.class}: #{e.message}"
+      )
+    end
+  end
+end

data/app/jobs/instagram_connect/send_message_job.rb

@@ -1,8 +1,11 @@
 module InstagramConnect
-  # Sends one pending outbound Message via the Graph API, exactly once. Claims
-  # the row (pending -> sending) with an atomic UPDATE so a duplicate enqueue
-  # can't double-send, then enforces Meta's messaging window — auto-applying the
-  # HUMAN_AGENT tag once the standard 24h window has passed.
+  # Sends one pending outbound Message via the Graph API, exactly once.
+  #
+  # The claim is an atomic UPDATE from pending to sending, so a duplicate
+  # enqueue cannot double-send. Everything after it keeps an at-most-once bias:
+  # on any doubt the message is marked failed for an operator to retry
+  # deliberately, never resent automatically. A duplicate message reaching a
+  # customer is worse than a visible failure.
   class SendMessageJob < ApplicationJob
     queue_as :default
 
@@ -12,33 +15,58 @@ module InstagramConnect
       return unless claimed == 1
 
       message = Message.find(message_id)
-      tag = MessagingWindow.new(last_inbound_at: message.conversation.last_inbound_at).send_tag
+      # The claim was callback-free, so a host rendering this thread live needs
+      # telling before the send starts rather than after it finishes.
+      message.broadcast_refresh
 
+      conversation = message.conversation
+
+      # Meta rejects a send on a thread another app owns, and the error it
+      # returns says nothing useful about why. Refusing here names the reason.
+      if conversation.controlled_elsewhere?
+        return fail_message(message, "thread_controlled_elsewhere",
+                            "Another app currently has control of this conversation.")
+      end
+
+      tag = MessagingWindow.new(last_inbound_at: conversation.last_inbound_at).send_tag
       if tag == :blocked
         return fail_message(message, "outside_messaging_window",
                             "The reply window has closed; the customer must message again.")
       end
 
-      deliver(message, tag)
+      deliver(message, conversation, tag)
     end
 
     private
 
-    def deliver(message, tag)
-      conversation = message.conversation
-      account = conversation.account
-      client = Client.new(access_token: account.access_token, ig_user_id: account.ig_user_id)
-      result = client.send_text(recipient_id: conversation.igsid, text: message.body.to_s, tag: tag)
-
-      if result.success?
-        message.update!(status: "sent", ig_message_id: result.id, message_tag: tag)
-      else
-        fail_message(message, result.error_code&.to_s, result.error_message)
+    def deliver(message, conversation, tag)
+      client = conversation.account.client
+      parts = TextSplitter.split(message.body.to_s)
+
+      # Resume rather than restart. A worker killed mid-fan-out has already
+      # delivered the earlier parts, and re-sending them repeats text the
+      # customer can already see.
+      parts.drop(message.delivered_parts_count).each do |part|
+        result = client.send_text(recipient_id: conversation.igsid, text: part, tag: tag)
+        return fail_message(message, result.error_code&.to_s, result.error_message) unless result.success?
+
+        message.update!(
+          delivered_parts_count: message.delivered_parts_count + 1,
+          # Meta returns an id per send. The first is the message's identity and
+          # the one its echo will carry back.
+          ig_message_id: message.ig_message_id.presence || result.id
+        )
       end
+
+      message.update!(status: "sent", message_tag: tag)
+      message.broadcast_refresh
+      message
     end
 
     def fail_message(message, reason, error)
       message.update!(status: "failed", failure_reason: reason, error_message: error)
+      message.broadcast_refresh
+      nil
     end
   end
 end

data/app/models/instagram_connect/account.rb

@@ -21,6 +21,29 @@ module InstagramConnect
     # Encryption configured can opt out via config.encrypt_tokens = false.
     def self.enable_token_encryption!
       encrypts :access_token
+      encrypts :page_access_token
+    end
+
+    # Every Instagram messaging call and the webhook subscription are Page-token
+    # operations. Falling back to the user token keeps a freshly connected
+    # account working until the readiness pass swaps in the Page one.
+    def api_token
+      page_access_token.presence || access_token
+    end
+
+    # The only place a Client should be built. Constructing one directly picks
+    # up the *global* auth path, which is wrong for any host with accounts on
+    # both paths — and wrong silently, which is worse.
+    def client
+      InstagramConnect::Client.new(
+        access_token: api_token,
+        ig_user_id: ig_user_id,
+        config: InstagramConnect.configuration.for_auth_path(auth_path)
+      )
+    end
+
+    def subscribed_field_list
+      subscribed_fields.to_s.split(",").map(&:strip).reject(&:empty?)
     end
 
     def token_expired?
@@ -28,8 +51,11 @@ module InstagramConnect
     end
 
     # Refresh via the account's auth strategy and persist the rotated token.
+    # Refreshes via the strategy this row was connected with, not the globally
+    # configured one.
     def refresh_access_token!
-      data = InstagramConnect::Auth.for(InstagramConnect.configuration).refresh_token(access_token: access_token)
+      strategy = InstagramConnect::Auth.for(InstagramConnect.configuration.for_auth_path(auth_path))
+      data = strategy.refresh_token(access_token: access_token)
       update!(access_token: data[:access_token], token_expires_at: data[:expires_at])
     end
   end

data/app/models/instagram_connect/api_budget.rb

@@ -0,0 +1,22 @@
+module InstagramConnect
+  # One rate-limit bucket for one account, for one window.
+  class ApiBudget < ApplicationRecord
+    self.table_name = "instagram_connect_api_budgets"
+
+    belongs_to :account, class_name: "InstagramConnect::Account"
+
+    validates :bucket, :window_start, :window_seconds, :limit_value, presence: true
+
+    def window_end
+      window_start + window_seconds
+    end
+
+    def blocked?
+      blocked_until.present? && blocked_until > Time.current
+    end
+
+    def exhausted?
+      used >= limit_value
+    end
+  end
+end

data/app/models/instagram_connect/conversation.rb

@@ -2,12 +2,21 @@ module InstagramConnect
   # One DM thread — a connected account talking to one Instagram user (igsid).
   # Threads are shared across the host's operators; ownership lives on the
   # account, not per-operator.
+  #
+  # Every writer here is SQL-side and monotonic. Meta guarantees no ordering
+  # across webhook batches, so a late-arriving older event must not roll a
+  # thread backwards, and concurrent inbound writes must not lose an unread
+  # increment.
   class Conversation < ApplicationRecord
     self.table_name = "instagram_connect_conversations"
 
+    FOLDERS = %w[primary general requests].freeze
+
     belongs_to :account, class_name: "InstagramConnect::Account"
     has_many :messages, class_name: "InstagramConnect::Message",
              foreign_key: :conversation_id, dependent: :destroy
+    has_many :reactions, class_name: "InstagramConnect::MessageReaction",
+             foreign_key: :conversation_id, dependent: :destroy
 
     validates :igsid, presence: true, uniqueness: { scope: :account_id }
 
@@ -23,21 +32,100 @@ module InstagramConnect
 
     # Denormalizes the thread summary + unread count atomically (SQL-side) so
     # concurrent inbound writes can't lose an unread increment.
+    #
+    # Keyed on the message's wire time, not our created_at: a webhook batch
+    # delayed by a redeploy would otherwise stamp old messages as the newest
+    # and reorder the inbox.
     def register_message(message)
-      stamp = message.created_at || Time.current
+      stamp = message.sent_at || message.created_at || Time.current
+      assignments = [
+        "last_message_at = #{monotonic('last_message_at')}",
+        "last_message_preview = ?",
+        "last_event_at = #{monotonic('last_event_at')}"
+      ]
+      binds = [ stamp, stamp, message.preview, stamp, stamp ]
+
       if message.inbound?
-        self.class.where(id: id).update_all([
-          "last_message_at = ?, last_message_preview = ?, last_inbound_at = ?, " \
-          "unread_count = unread_count + 1, updated_at = ?",
-          stamp, message.preview, stamp, Time.current
-        ])
-      else
-        self.class.where(id: id).update_all([
-          "last_message_at = ?, last_message_preview = ?, updated_at = ?",
-          stamp, message.preview, Time.current
-        ])
+        assignments << "last_inbound_at = #{monotonic('last_inbound_at')}"
+        assignments << "unread_count = unread_count + 1"
+        binds += [ stamp, stamp ]
       end
+
+      apply(assignments, binds)
+    end
+
+    # A read receipt only ever moves forward. A stale one redelivered after a
+    # newer message must not mark the thread read again.
+    def mark_read_by_customer(at:, mid: nil)
+      apply(
+        [
+          "customer_last_read_mid = CASE WHEN customer_last_read_at IS NULL " \
+          "OR customer_last_read_at < ? THEN ? ELSE customer_last_read_mid END",
+          "customer_last_read_at = #{monotonic('customer_last_read_at')}",
+          "last_event_at = #{monotonic('last_event_at')}"
+        ],
+        [ at, mid, at, at, at, at ]
+      )
+      mark_outbound_seen(at)
+      self
+    end
+
+    def register_referral(ref:, at:)
+      apply(
+        [
+          "last_referral_ref = CASE WHEN last_event_at IS NULL OR last_event_at < ? " \
+          "THEN ? ELSE last_referral_ref END",
+          "last_event_at = #{monotonic('last_event_at')}"
+        ],
+        [ at, ref, at, at ]
+      )
+    end
+
+    def register_thread_control(owner_app_id:, at:)
+      apply(
+        [
+          "thread_owner_app_id = CASE WHEN thread_control_at IS NULL OR thread_control_at < ? " \
+          "THEN ? ELSE thread_owner_app_id END",
+          "thread_control_at = #{monotonic('thread_control_at')}",
+          "last_event_at = #{monotonic('last_event_at')}"
+        ],
+        [ at, owner_app_id, at, at, at, at ]
+      )
+    end
+
+    # Any activity that is not a message — a reaction, an opt-in — still counts
+    # as the thread being alive, and still reopens Meta's 24-hour window.
+    def register_event(at)
+      apply([ "last_event_at = #{monotonic('last_event_at')}" ], [ at, at ])
+    end
+
+    # True when another app (typically the Page Inbox) holds thread control, in
+    # which case the Send API rejects our messages.
+    def controlled_elsewhere?
+      thread_control_at.present? && thread_owner_app_id.present?
+    end
+
+    private
+
+    # SQLite has no GREATEST, so the monotonic guard is spelled as a CASE. Two
+    # binds per use: the comparison value and the value to store.
+    def monotonic(column)
+      "CASE WHEN #{column} IS NULL OR #{column} < ? THEN ? ELSE #{column} END"
+    end
+
+    def apply(assignments, binds)
+      self.class.where(id: id).update_all(
+        [ "#{assignments.join(', ')}, updated_at = ?", *binds, Time.current ]
+      )
       reload
     end
+
+    # The receipt covers everything the customer had received, so every earlier
+    # outbound message is seen too — Meta sends one receipt, not one per bubble.
+    def mark_outbound_seen(at)
+      messages.where(direction: "outbound", seen_at: nil)
+              .where(sent_at: ..at)
+              .update_all(seen_at: at, updated_at: Time.current)
+    end
   end
 end