instagram_connect 0.2.1 → 0.3.0

data/db/migrate/20260725203215_create_instagram_connect_insight_snapshots.rb

@@ -0,0 +1,45 @@
+class CreateInstagramConnectInsightSnapshots < ActiveRecord::Migration[7.1]
+  # Metric readings, kept because Meta does not keep them for long: story
+  # metrics are retrievable for 24 hours, account metrics for 90 days, media
+  # metrics for two years. A dashboard reading straight from the API can only
+  # ever show that window.
+  #
+  # Story insights are the acute case. The `story_insights` webhook fires when a
+  # story expires and carries its final metrics — that delivery is the only
+  # chance to record them, so its handler writes here synchronously rather than
+  # deferring to a job that might not run in time.
+  def change
+    create_table :instagram_connect_insight_snapshots, if_not_exists: true do |t|
+      t.bigint :account_id, null: false
+      t.string :subject_type, null: false
+      t.string :subject_ref
+      t.string :period, null: false
+      t.date :period_start, null: false
+      t.string :breakdown
+      # webhook | api. Part of the uniqueness key so the poller overwrites its
+      # own readings all day without ever colliding with the webhook's final
+      # one, and a dropped webhook still leaves the last mid-life reading.
+      t.string :source, null: false, default: "api"
+      t.column :metrics, json_type, null: false
+      # A metric Meta declines to report is absent from metrics rather than
+      # zero — these flags are how a UI tells "not reported" from "really zero".
+      t.boolean :empty, null: false, default: false
+      t.boolean :suppressed, null: false, default: false
+      t.integer :error_code
+      t.datetime :captured_at, null: false
+      t.timestamps
+    end
+
+    add_index :instagram_connect_insight_snapshots,
+              [ :account_id, :subject_type, :subject_ref, :period, :period_start, :breakdown, :source ],
+              unique: true, name: "index_instagram_connect_snapshots_unique", if_not_exists: true
+    add_index :instagram_connect_insight_snapshots, [ :account_id, :captured_at ],
+              name: "index_instagram_connect_snapshots_on_account_and_time", if_not_exists: true
+  end
+
+  private
+
+  def json_type
+    connection.adapter_name.match?(/postg/i) ? :jsonb : :json
+  end
+end

data/db/migrate/20260725203306_add_comment_moderation_fields.rb

@@ -0,0 +1,29 @@
+class AddCommentModerationFields < ActiveRecord::Migration[7.1]
+  COLUMNS = {
+    # The commenter's Instagram-scoped id. Needed to send them a private reply,
+    # which the username alone cannot address.
+    from_ig_id: { type: :string },
+    commented_at: { type: :datetime },
+    like_count: { type: :integer },
+    # From the live_comments field. A private reply to a live comment is valid
+    # only while the broadcast is running, so this is what stops the UI offering
+    # a button that is already guaranteed to fail.
+    is_live: { type: :boolean, default: false, null: false },
+    deleted_at: { type: :datetime },
+    # Distinct from replied_at, which is a public reply. The private reply is a
+    # separate, spendable resource: one per commenter, expiring 7 days after the
+    # comment.
+    private_replied_at: { type: :datetime },
+    private_reply_message_id: { type: :bigint }
+  }.freeze
+
+  def change
+    COLUMNS.each do |name, options|
+      add_column :instagram_connect_comments, name, options[:type],
+                 **options.except(:type), if_not_exists: true
+    end
+
+    add_index :instagram_connect_comments, [ :account_id, :commented_at ],
+              name: "index_instagram_connect_comments_on_account_and_time", if_not_exists: true
+  end
+end

data/db/migrate/20260725204022_add_per_account_token_fields.rb

@@ -0,0 +1,76 @@
+class AddPerAccountTokenFields < ActiveRecord::Migration[7.1]
+  ACCOUNT_COLUMNS = {
+    # The OAuth exchange returns a *user* token, but every Instagram messaging
+    # endpoint and the webhook subscription are Page-token operations. Keeping
+    # them in separate columns is what lets the readiness pass tell which grade
+    # it is holding instead of guessing.
+    page_access_token: { type: :text },
+    page_token_verified_at: { type: :datetime },
+    # Set when a Page call comes back with an auth error. There is no silent
+    # recovery from this — the operator has to reconnect — so it surfaces as a
+    # flag rather than as a retry that can never succeed.
+    needs_reconnect: { type: :boolean, default: false, null: false },
+    readiness_error: { type: :string },
+    # The fields the Page is actually subscribed to, as last read from Meta.
+    # Lets the readiness pass skip a POST it does not need, and lets a health
+    # screen show what is really live rather than what we hoped.
+    subscribed_fields: { type: :text },
+    subscriptions_synced_at: { type: :datetime },
+    name: { type: :string },
+    profile_picture_url: { type: :text },
+    profile_synced_at: { type: :datetime }
+  }.freeze
+
+  def change
+    ACCOUNT_COLUMNS.each do |name, options|
+      add_column :instagram_connect_accounts, name, options[:type],
+                 **options.except(:type), if_not_exists: true
+    end
+
+    add_column :instagram_connect_messages, :account_id, :bigint, if_not_exists: true
+
+    reversible do |dir|
+      dir.up { backfill_message_accounts }
+    end
+
+    # Uniqueness has to be per account, not global. With two connected accounts
+    # that message each other, the echo's mid is claimed by whichever processes
+    # first and permanently dropped for the other — a live correctness bug, not
+    # hygiene. Same reasoning for comments and the inbound ledger.
+    add_index :instagram_connect_messages, [ :account_id, :ig_message_id ],
+              unique: true, name: "index_instagram_connect_messages_on_account_and_mid",
+              if_not_exists: true
+    remove_index :instagram_connect_messages, column: :ig_message_id, if_exists: true
+
+    add_index :instagram_connect_comments, [ :account_id, :comment_id ],
+              unique: true, name: "index_instagram_connect_comments_on_account_and_comment",
+              if_not_exists: true
+    remove_index :instagram_connect_comments, column: :comment_id, if_exists: true
+
+    add_index :instagram_connect_inbound_messages, [ :account_id, :ig_message_id ],
+              unique: true, name: "index_instagram_connect_inbound_on_account_and_mid",
+              if_not_exists: true
+    remove_index :instagram_connect_inbound_messages, column: :ig_message_id, if_exists: true
+  end
+
+  private
+
+  # Denormalized from the conversation so account-scoped inbox queries and
+  # stream names do not need a join. Filled inline because the new unique index
+  # is only meaningful once it is populated — a NULL account_id would let the
+  # very duplicates this index exists to prevent slip through.
+  #
+  # A correlated subquery rather than UPDATE...FROM, which is Postgres-only.
+  # An adopter with millions of messages should run this chunked before
+  # upgrading; at the scale this gem is written for it is a single indexed pass.
+  def backfill_message_accounts
+    execute(<<~SQL.squish)
+      UPDATE instagram_connect_messages
+      SET account_id = (
+        SELECT account_id FROM instagram_connect_conversations
+        WHERE instagram_connect_conversations.id = instagram_connect_messages.conversation_id
+      )
+      WHERE account_id IS NULL
+    SQL
+  end
+end

data/db/migrate/20260725204815_create_instagram_connect_api_budgets.rb

@@ -0,0 +1,29 @@
+class CreateInstagramConnectApiBudgets < ActiveRecord::Migration[7.1]
+  # A shared, durable counter per account per rate-limit bucket.
+  #
+  # Meta's limits are per Instagram account, not per process, so a counter held
+  # in memory is wrong the moment there is more than one worker — and resets to
+  # zero on every deploy, which is exactly when a backlog is most likely to
+  # burst through the ceiling. A row with a unique key on the window makes the
+  # increment atomic across processes in one statement.
+  def change
+    create_table :instagram_connect_api_budgets, if_not_exists: true do |t|
+      t.bigint :account_id, null: false
+      t.string :bucket, null: false
+      t.datetime :window_start, null: false
+      t.integer :window_seconds, null: false
+      t.integer :used, null: false, default: 0
+      t.integer :limit_value, null: false
+      # Set when Meta says outright that we are throttled. Until it passes,
+      # every job for this account refuses immediately rather than each one
+      # rediscovering the block for itself.
+      t.datetime :blocked_until
+      t.timestamps
+    end
+
+    add_index :instagram_connect_api_budgets, [ :account_id, :bucket, :window_start ],
+              unique: true, name: "index_instagram_connect_budgets_unique", if_not_exists: true
+    add_index :instagram_connect_api_budgets, [ :account_id, :bucket, :blocked_until ],
+              name: "index_instagram_connect_budgets_on_blocked", if_not_exists: true
+  end
+end

data/db/migrate/20260725205417_add_conversation_profile_fields.rb

@@ -0,0 +1,21 @@
+class AddConversationProfileFields < ActiveRecord::Migration[7.1]
+  # username and display_name already existed on conversations and nothing ever
+  # wrote them, so an inbox showed raw Instagram-scoped ids — a 17-digit number
+  # where a person's handle belongs. These are the rest of what a thread row
+  # needs to look like a conversation with somebody.
+  def change
+    add_column :instagram_connect_conversations, :profile_picture_url, :text, if_not_exists: true
+    add_column :instagram_connect_conversations, :profile_synced_at, :datetime, if_not_exists: true
+
+    # Partial indexes are Postgres-only, and this gem ships into whatever
+    # database the host runs.
+    add_index :instagram_connect_conversations, [ :account_id, :profile_synced_at ],
+              name: "index_instagram_connect_conversations_on_profile_sync",
+              if_not_exists: true
+
+    # Cheap header stats, and the input to the 4800 x impressions budget the
+    # rate limiter falls back on when Meta sends no usage header.
+    add_column :instagram_connect_accounts, :followers_count, :integer, if_not_exists: true
+    add_column :instagram_connect_accounts, :media_count, :integer, if_not_exists: true
+  end
+end

data/docs/CONFIGURATION.md

@@ -0,0 +1,107 @@
+# Configuration reference
+
+Every setting lives on `InstagramConnect::Configuration` and is set inside the
+`InstagramConnect.configure` block (usually
+`config/initializers/instagram_connect.rb`):
+
+```ruby
+InstagramConnect.configure do |config|
+  config.auth_path = :instagram_login
+  # ...
+end
+```
+
+You can also set any of these through `config.instagram_connect = { ... }` in
+your Rails app configuration; the engine (and the railtie) applies each key
+through the matching setter at boot.
+
+Several secrets fall back to environment variables, so a host can configure them
+entirely from the environment without editing the initializer. The `configure`
+block runs `validate!`, which currently checks only that `auth_path` is one of
+the known values; missing secrets are reported later, at the point of use, and
+by the `doctor` CLI.
+
+## Core
+
+| Setting | Type | Default | Environment fallback | Purpose |
+| --- | --- | --- | --- | --- |
+| `auth_path` | Symbol | `:instagram_login` | `INSTAGRAM_CONNECT_AUTH_PATH` | Which Meta login path and Graph host to use. One of `:instagram_login` (graph.instagram.com, no Facebook Page) or `:facebook_login` (graph.facebook.com, linked Page). Accepts a string and coerces it to a symbol. |
+| `app_id` | String | `nil` | `INSTAGRAM_CONNECT_APP_ID`, then `INSTAGRAM_APP_ID` | Your Meta app's client id. |
+| `app_secret` | String | `nil` | `INSTAGRAM_CONNECT_APP_SECRET`, then `INSTAGRAM_APP_SECRET` | Your Meta app's secret. Used for the OAuth code exchange and for verifying the webhook HMAC signature. |
+| `verify_token` | String | `nil` | `INSTAGRAM_CONNECT_VERIFY_TOKEN`, then `INSTAGRAM_VERIFY_TOKEN` | The token you enter in the Meta webhook dashboard. The GET verification handshake must present this value. |
+| `graph_version` | String | `"v21.0"` | `INSTAGRAM_CONNECT_GRAPH_VERSION` | The Graph API version segment in request URLs. |
+| `redirect_uri` | String | `nil` | `INSTAGRAM_CONNECT_REDIRECT_URI` | Pin the OAuth redirect URI. Meta requires an exact match. When blank, the engine uses its own callback URL. |
+
+## Token storage
+
+| Setting | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `encrypt_tokens` | Boolean | `true` | Encrypt `Account#access_token` at rest with Active Record Encryption. Set to `false` if your app has no encryption configured. When true, run `bin/rails db:encryption:init` once and add the generated keys to your credentials. |
+
+## Rails integration
+
+| Setting | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `parent_controller` | String | `"::ApplicationController"` | The controller the engine's UI controllers inherit from, so they pick up the host layout, auth helpers, and CSRF handling. The webhook controller does not inherit from this. |
+| `authenticate_with` | Callable | `nil` | A lambda run as a `before_action` in the engine's controllers. Put your host's sign-in guard here, for example `-> { authenticate_user! }`. |
+| `current_user_id_resolver` | Callable | resolves `current_user&.id` in controller context | Attributes outbound replies and connected accounts to the acting operator. Runs in controller context. |
+| `inherit_host_layout` | Boolean | `false` | When `false`, the engine renders in its own bundled layout and stylesheet, like an admin engine. Set `true` to render inside your app's `application` layout, then add `<%= instagram_connect_styles %>` to your `<head>`. |
+| `default_per_page` | Integer | `25` | Page size for the inbox and comment lists. |
+| `after_connect_redirect` | String | `"/"` | Where the OAuth callback redirects after an account is connected. The install generator sets this to `/instagram/conversations`. |
+
+## Event hooks
+
+Each hook is optional and receives the persisted record (or event hash) after
+the webhook payload has been ingested, so you can layer on notifications, AI
+replies, and the like.
+
+| Setting | Type | Default | Receives |
+| --- | --- | --- | --- |
+| `on_message` | Callable | `nil` | The `InstagramConnect::Message` created for an inbound DM (not fired for echoes of your own outbound sends). |
+| `on_comment` | Callable | `nil` | The `InstagramConnect::Comment` recorded from a `comments` change. |
+| `on_postback` | Callable | `nil` | A hash: `{ account_id:, sender_id:, payload:, title: }`. |
+
+## Logging
+
+| Setting | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `logger` | Logger | `Logger.new($stdout)` | Where the gem logs. The token refresh job logs per-account failures here. |
+
+## Theme
+
+The gem ships a complete, self-styled UI. Tint it by assigning `config.theme` a
+hash of any subset of the keys below; your values are merged over the defaults
+(`resolved_theme`) and emitted as CSS custom properties by
+`instagram_connect_styles`.
+
+```ruby
+config.theme = { primary: "#0057a8", font: "Inter, system-ui, sans-serif", radius: "12px" }
+```
+
+| Key | Default |
+| --- | --- |
+| `primary` | `#2563eb` |
+| `primary_contrast` | `#ffffff` |
+| `bg` | `#f7f8fa` |
+| `surface` | `#ffffff` |
+| `text` | `#111827` |
+| `muted` | `#6b7280` |
+| `border` | `#e5e7eb` |
+| `radius` | `12px` |
+| `font` | `Inter, system-ui, -apple-system, Segoe UI, Roboto, sans-serif` |
+| `customer_bubble` | `#f1f3f5` |
+| `staff_bubble` | `#eef2ff` |
+| `ok` | `#16a34a` |
+| `warn` | `#d97706` |
+| `err` | `#dc2626` |
+
+## Media
+
+These are defined on the configuration object with the defaults below. They are
+reserved for the inbound and outbound media handling on the roadmap and are not
+yet read by the shipped code.
+
+| Setting | Type | Default |
+| --- | --- | --- |
+| `media_max_bytes` | Integer | `26214400` (25 MB) |
+| `allowed_media_types` | Array | `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `video/mp4`, `audio/mpeg`, `audio/aac`, `application/pdf` |

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