instagram_connect 0.2.1 → 0.3.0

data/app/models/instagram_connect/inbound_message.rb

@@ -1,10 +1,18 @@
 module InstagramConnect
-  # At-least-once dedupe ledger keyed by Meta's message id. Lets the webhook
-  # (and any future backfill/poll) run without double-processing a message.
+  # Dedupe ledger keyed by Meta's message id, scoped to an account.
+  #
+  # DEPRECATED, removal at 1.0. WebhookEvent is the claim now: keying every
+  # event type on one message id is wrong once other fields carry the same id —
+  # a messaging_seen receipt names the mid of a message already claimed here, so
+  # claiming it would swallow either the receipt or the message. This is kept in
+  # step so a host querying it against 0.2.x behaviour still sees every message.
   class InboundMessage < ApplicationRecord
     self.table_name = "instagram_connect_inbound_messages"
 
-    # Returns true only the first time a given message id is claimed.
+    # Returns true only the first time a message id is claimed for an account.
+    # Uniqueness is scoped per account: two connected accounts messaging each
+    # other share a mid, and a global claim would drop it for whichever account
+    # processed second. A nil account_id therefore no longer dedupes at all.
     def self.claim(ig_message_id:, account_id: nil)
       create!(ig_message_id: ig_message_id, account_id: account_id, processed_at: Time.current)
       true

data/app/models/instagram_connect/insight_snapshot.rb

@@ -0,0 +1,43 @@
+module InstagramConnect
+  # One reading of a set of metrics, kept because Meta's own retention is short
+  # and, for stories, measured in hours.
+  class InsightSnapshot < ApplicationRecord
+    self.table_name = "instagram_connect_insight_snapshots"
+
+    SUBJECT_TYPES = %w[account media story].freeze
+    SOURCES = %w[api webhook].freeze
+
+    belongs_to :account, class_name: "InstagramConnect::Account"
+
+    validates :subject_type, inclusion: { in: SUBJECT_TYPES }
+    validates :source, inclusion: { in: SOURCES }
+    validates :period, :period_start, :captured_at, presence: true
+
+    scope :for_subject, ->(type, ref) { where(subject_type: type, subject_ref: ref) }
+    scope :chronological, -> { order(:period_start, :id) }
+
+    # Upsert on the natural key. The API poller overwrites its own reading as a
+    # story accrues views; the webhook's final reading is a separate row because
+    # source is part of the key, so neither can clobber the other.
+    def self.record(account:, subject_type:, period:, period_start:, metrics:, captured_at:,
+                    subject_ref: nil, breakdown: nil, source: "api", empty: false,
+                    suppressed: false, error_code: nil)
+      snapshot = find_or_initialize_by(
+        account_id: account.id, subject_type: subject_type, subject_ref: subject_ref,
+        period: period, period_start: period_start, breakdown: breakdown, source: source
+      )
+      snapshot.assign_attributes(
+        metrics: metrics, captured_at: captured_at, empty: empty,
+        suppressed: suppressed, error_code: error_code
+      )
+      snapshot.save!
+      snapshot
+    end
+
+    # nil means Meta did not report the metric, which is not the same as zero —
+    # so callers must never reach for a default here.
+    def value(metric)
+      metrics.is_a?(Hash) ? metrics[metric.to_s] : nil
+    end
+  end
+end

data/app/models/instagram_connect/media_item.rb

@@ -0,0 +1,38 @@
+module InstagramConnect
+  # A post, reel or story on the connected account — "IG Media" in Meta's
+  # vocabulary. Named MediaItem because InstagramConnect::Media is already the
+  # namespace for inbound file handling (Media::Limits, Media::Attaching); the
+  # table keeps Meta's noun.
+  class MediaItem < ApplicationRecord
+    self.table_name = "instagram_connect_media"
+
+    PRODUCT_TYPES = %w[FEED STORY REELS AD].freeze
+
+    belongs_to :account, class_name: "InstagramConnect::Account"
+    has_many :insight_snapshots, -> { where(subject_type: "media") },
+             class_name: "InstagramConnect::InsightSnapshot",
+             foreign_key: :subject_ref, primary_key: :ig_media_id,
+             dependent: :destroy, inverse_of: false
+
+    validates :ig_media_id, presence: true, uniqueness: { scope: :account_id }
+
+    scope :stories, -> { where(media_product_type: "STORY") }
+    scope :recent, -> { order(Arel.sql("posted_at IS NULL, posted_at DESC")) }
+
+    # Upserts by Meta's id. Media arrives from several directions — a webhook
+    # about a comment, a story expiring, a sync — and whichever gets there first
+    # should create the row without the others having to care.
+    def self.record(account:, ig_media_id:, **attributes)
+      media = find_or_initialize_by(account_id: account.id, ig_media_id: ig_media_id.to_s)
+      media.assign_attributes(attributes.compact)
+      media.save!
+      media
+    rescue ActiveRecord::RecordNotUnique
+      find_by!(account_id: account.id, ig_media_id: ig_media_id.to_s)
+    end
+
+    def story?
+      media_product_type == "STORY"
+    end
+  end
+end

data/app/models/instagram_connect/mention.rb

@@ -0,0 +1,37 @@
+module InstagramConnect
+  # An @mention of the account, in a comment, a caption or a tag.
+  #
+  # Meta does not store these notifications and will not resend them, so this
+  # table is the only record that a mention ever happened.
+  class Mention < ApplicationRecord
+    self.table_name = "instagram_connect_mentions"
+
+    KINDS = %w[comment caption tag story].freeze
+
+    belongs_to :account, class_name: "InstagramConnect::Account"
+    belongs_to :message, class_name: "InstagramConnect::Message", optional: true
+
+    validates :kind, inclusion: { in: KINDS }
+    validates :mentioned_at, presence: true
+
+    scope :unanswered, -> { where(replied_at: nil) }
+    scope :recent, -> { order(mentioned_at: :desc) }
+
+    def self.record(account:, kind:, mentioned_at:, ig_media_id: nil, comment_id: nil, **attributes)
+      mention = find_or_initialize_by(
+        account_id: account.id, kind: kind,
+        ig_media_id: ig_media_id.presence, comment_id: comment_id.presence
+      )
+      mention.assign_attributes(attributes.compact.merge(mentioned_at: mentioned_at))
+      mention.save!
+      mention
+    rescue ActiveRecord::RecordNotUnique
+      find_by!(account_id: account.id, kind: kind,
+               ig_media_id: ig_media_id.presence, comment_id: comment_id.presence)
+    end
+
+    def answered?
+      replied_at.present?
+    end
+  end
+end

data/app/models/instagram_connect/message.rb

@@ -5,12 +5,21 @@ module InstagramConnect
 
     DIRECTIONS = %w[inbound outbound].freeze
     STATUSES = %w[received pending sending sent failed].freeze
-    KINDS = %w[dm story_reply reaction].freeze
+    KINDS = %w[dm story_reply story_mention reaction postback share unsupported].freeze
     SOURCES = %w[inbound manual api operator_app].freeze
     MEDIA_STATUSES = %w[none pending downloadable attached unavailable].freeze
     PREVIEW_LIMIT = 140
 
     belongs_to :conversation, class_name: "InstagramConnect::Conversation"
+    # Denormalized from the conversation so account-scoped queries and stream
+    # names do not need a join, and so uniqueness can be scoped per account.
+    before_validation :inherit_account_id
+
+    has_many :attachments, -> { order(:position) },
+             class_name: "InstagramConnect::MessageAttachment",
+             foreign_key: :message_id, dependent: :destroy
+    has_many :reactions, class_name: "InstagramConnect::MessageReaction",
+             foreign_key: :message_id, dependent: :nullify
 
     validates :direction, inclusion: { in: DIRECTIONS }
     validates :status, inclusion: { in: STATUSES }
@@ -18,7 +27,24 @@ module InstagramConnect
 
     scope :inbound, -> { where(direction: "inbound") }
     scope :outbound, -> { where(direction: "outbound") }
-    scope :chronological, -> { order(:created_at, :id) }
+    # Ordered by Meta's clock, falling back to ours for rows written before
+    # sent_at existed. A webhook batch delayed by a redeploy would otherwise
+    # reorder the thread.
+    scope :chronological, -> { order(Arel.sql("COALESCE(sent_at, created_at)"), :id) }
+
+    # Extension point: a host rendering this record live overrides it to
+    # re-broadcast current state after a callback-free write (update_all, which
+    # the send and media paths both use to stay atomic). A no-op here keeps the
+    # gem free of any Turbo dependency.
+    def broadcast_refresh; end
+
+    def occurred_at
+      sent_at || created_at
+    end
+
+    def deleted?
+      deleted_at.present?
+    end
 
     def inbound?
       direction == "inbound"
@@ -33,5 +59,11 @@ module InstagramConnect
       return body.to_s.truncate(PREVIEW_LIMIT) if body.present?
       "[#{kind}]"
     end
+
+    private
+
+    def inherit_account_id
+      self.account_id ||= conversation&.account_id
+    end
   end
 end

data/app/models/instagram_connect/message_attachment.rb

@@ -0,0 +1,53 @@
+module InstagramConnect
+  # One file on a message. Rows are created at ingest with everything already
+  # decided except the bytes, which a job fetches separately.
+  class MessageAttachment < ApplicationRecord
+    self.table_name = "instagram_connect_message_attachments"
+
+    # Instagram gives no second chance at inbound media: the CDN URL expires and
+    # there is no endpoint to ask again. So there is no "downloadable" state
+    # here as there is for transports that keep the file — an attachment either
+    # lands in storage or is permanently unavailable.
+    STATES = %w[pending attached unavailable skipped].freeze
+
+    # Meta's own vocabulary for what the attachment is, which is not the same
+    # question as what MIME type the bytes turn out to be.
+    KINDS = %w[image video audio file share story_mention ig_reel reel template].freeze
+
+    belongs_to :message, class_name: "InstagramConnect::Message"
+
+
+    validates :position, presence: true, uniqueness: { scope: :message_id }
+    validates :kind, presence: true
+    validates :state, inclusion: { in: STATES }
+
+    # Called from the engine's to_prepare when Active Storage is present, the
+    # same shape as Account.enable_token_encryption!. The gem does not depend on
+    # Active Storage, so a host without it still boots and simply keeps the
+    # attachment rows as metadata without ever fetching bytes.
+    def self.enable_file_attachment!
+      has_one_attached :file
+    end
+
+    scope :pending, -> { where(state: "pending") }
+    scope :ordered, -> { order(:position) }
+
+    def fetchable?
+      state == "pending" && source_url.present?
+    end
+
+    def attached?
+      state == "attached"
+    end
+
+    def mark_attached!(mime:, size:, filename: nil)
+      update!(state: "attached", mime: mime, size: size, filename: filename, error: nil)
+    end
+
+    # Terminal. Nothing retries after this, because retrying a URL Instagram has
+    # already expired only burns the rate budget.
+    def mark_unavailable!(reason)
+      update!(state: "unavailable", error: reason.to_s.truncate(255))
+    end
+  end
+end

data/app/models/instagram_connect/message_reaction.rb

@@ -0,0 +1,33 @@
+module InstagramConnect
+  # One reaction event on a message. Append-only — see the migration for why
+  # current state is a read rather than a column.
+  class MessageReaction < ApplicationRecord
+    self.table_name = "instagram_connect_message_reactions"
+
+    ACTIONS = %w[react unreact].freeze
+    ACTORS = %w[customer business].freeze
+
+    belongs_to :conversation, class_name: "InstagramConnect::Conversation"
+    belongs_to :message, class_name: "InstagramConnect::Message", optional: true
+
+    validates :ig_message_id, :igsid, :reacted_at, presence: true
+    validates :action, inclusion: { in: ACTIONS }
+    validates :actor, inclusion: { in: ACTORS }
+
+    scope :chronological, -> { order(:reacted_at, :id) }
+
+    # The reaction currently showing on a message, or nil if the last event was
+    # an unreact. Reading MAX(reacted_at) rather than trusting arrival order is
+    # what makes out-of-order delivery harmless.
+    def self.current_for(ig_message_id)
+      latest = where(ig_message_id: ig_message_id).chronological.last
+      return nil if latest.nil? || latest.action == "unreact"
+
+      latest
+    end
+
+    def react?
+      action == "react"
+    end
+  end
+end

data/app/models/instagram_connect/webhook_event.rb

@@ -0,0 +1,67 @@
+module InstagramConnect
+  # One row per webhook event Meta delivered, stored verbatim before anything
+  # interprets it. See the migration for why this exists rather than a counter.
+  class WebhookEvent < ApplicationRecord
+    self.table_name = "instagram_connect_webhook_events"
+
+    STATUSES = %w[pending processed unhandled failed].freeze
+
+    belongs_to :account, class_name: "InstagramConnect::Account", optional: true
+    belongs_to :subject, polymorphic: true, optional: true
+
+    validates :field, :event_type, :dedupe_key, presence: true
+    validates :status, inclusion: { in: STATUSES }
+
+    scope :pending, -> { where(status: "pending") }
+    scope :replayable, -> { where(status: %w[pending unhandled failed]) }
+    scope :for_field, ->(field) { where(field: field) }
+    scope :chronological, -> { order(:occurred_at, :id) }
+
+    # Claims an event for processing, or returns nil if this exact event was
+    # already delivered. Meta retries webhooks it considers unacknowledged, so
+    # duplicates are routine rather than exceptional — the unique index on
+    # [field, dedupe_key] is what makes the claim atomic under concurrency.
+    def self.claim(field:, dedupe_key:, event_type:, payload:, account: nil,
+                   object: nil, entry_id: nil, occurred_at: nil, handler: nil)
+      create!(
+        account: account,
+        object: object,
+        field: field,
+        event_type: event_type,
+        dedupe_key: dedupe_key,
+        entry_id: entry_id,
+        occurred_at: occurred_at,
+        received_at: Time.current,
+        handler: handler,
+        payload: payload,
+        status: "pending"
+      )
+    rescue ActiveRecord::RecordNotUnique
+      nil
+    end
+
+    def mark_processed!(subject = nil)
+      update!(status: "processed", processed_at: Time.current, subject: subject)
+    end
+
+    # Recorded, not dropped: a field the gem does not parse yet is still worth
+    # keeping, because replaying it later is the only way to recover events Meta
+    # will never send again.
+    def mark_unhandled!
+      update!(status: "unhandled", processed_at: Time.current)
+    end
+
+    def mark_failed!(error)
+      update!(
+        status: "failed",
+        processed_at: Time.current,
+        error_class: error.class.name,
+        error_message: error.message.to_s.truncate(1000)
+      )
+    end
+
+    def processed?
+      status == "processed"
+    end
+  end
+end

data/db/migrate/20260725194732_create_instagram_connect_webhook_events.rb

@@ -0,0 +1,52 @@
+class CreateInstagramConnectWebhookEvents < ActiveRecord::Migration[7.1]
+  # Every webhook event Meta delivers, stored verbatim before anything tries to
+  # interpret it.
+  #
+  # Meta does not store `mentions` or `story_insights` notifications and never
+  # re-delivers any event, so a parse bug against a live payload is permanent
+  # data loss. With this table it is a re-runnable row instead. It also lets an
+  # operator subscribe a field at Meta before its handler exists — the events
+  # bank as "unhandled" and ReplayEventsJob walks them once the handler ships.
+  def change
+    create_table :instagram_connect_webhook_events, if_not_exists: true do |t|
+      # Nullable: an entry whose id matches no connected account is recorded
+      # rather than dropped. That is how you discover a second Page was
+      # connected to the app, instead of losing a week of DMs to a counter.
+      t.bigint :account_id
+      t.string :object
+      t.string :field, null: false
+      t.string :event_type, null: false
+      t.string :dedupe_key, null: false
+      t.string :entry_id
+      t.datetime :occurred_at
+      t.datetime :received_at, null: false
+      t.datetime :processed_at
+      t.string :status, null: false, default: "pending"
+      t.string :handler
+      t.string :error_class
+      t.text :error_message
+      t.integer :attempts, null: false, default: 0
+      t.string :subject_type
+      t.bigint :subject_id
+      t.column :payload, json_type, null: false
+      t.timestamps
+    end
+
+    add_index :instagram_connect_webhook_events, [ :field, :dedupe_key ],
+              unique: true, if_not_exists: true
+    add_index :instagram_connect_webhook_events, [ :account_id, :field, :occurred_at ],
+              name: "index_instagram_connect_webhook_events_on_account_field_time",
+              if_not_exists: true
+    add_index :instagram_connect_webhook_events, [ :status, :created_at ], if_not_exists: true
+    add_index :instagram_connect_webhook_events, [ :subject_type, :subject_id ], if_not_exists: true
+  end
+
+  private
+
+  # The gem ships into whichever database the host runs. jsonb is the right
+  # column on Postgres and does not exist on SQLite, so pick per adapter rather
+  # than forcing every adopter onto one.
+  def json_type
+    connection.adapter_name.match?(/postg/i) ? :jsonb : :json
+  end
+end

data/db/migrate/20260725200216_add_messaging_event_fields.rb

@@ -0,0 +1,89 @@
+class AddMessagingEventFields < ActiveRecord::Migration[7.1]
+  # Columns for the messaging events beyond plain DMs — reactions, read
+  # receipts, referrals, thread handover, quick replies, story replies — plus
+  # the wire clock all of their ordering depends on.
+  #
+  # Written as individual add_column calls rather than a bulk change_table
+  # because only add_column honours if_not_exists, and every migration this gem
+  # ships has to survive being re-run against a database that already has the
+  # columns (0.2.1 shipped to fix exactly that).
+  MESSAGE_COLUMNS = {
+    # Meta's own timestamp. Ordering used our created_at, so a webhook batch
+    # delayed by a redeploy silently reordered a thread. Backfilled below, and
+    # left nullable on purpose: promoting it to NOT NULL takes a lock this gem
+    # cannot know the cost of in an adopter's database.
+    sent_at: { type: :datetime },
+    seen_at: { type: :datetime },
+    # The customer unsent the message. The row is never destroyed — the thread
+    # should read "message unsent" rather than lose its shape. Erasing it is a
+    # host policy decision, not a gem default.
+    deleted_at: { type: :datetime },
+    unsupported: { type: :boolean, default: false, null: false },
+    reply_to_mid: { type: :string },
+    quick_reply_payload: { type: :string },
+    postback_payload: { type: :string },
+    postback_title: { type: :string },
+    referral_ref: { type: :string },
+    referral_source: { type: :string },
+    referral_type: { type: :string },
+    referral_product_id: { type: :string },
+    story_id: { type: :string },
+    story_url: { type: :text },
+    # The wire attachment type (image, video, story_mention, ig_reel...),
+    # orthogonal to the MIME type of the bytes behind it.
+    media_kind: { type: :string },
+    # Projections of the reaction log, so a bubble renders without a join.
+    reactions_count: { type: :integer, default: 0, null: false },
+    last_reaction: { type: :string }
+  }.freeze
+
+  CONVERSATION_COLUMNS = {
+    # Meta splits threads into primary/general/requests. A requests thread idle
+    # for 30 days stops being returned by the Conversations API at all, so the
+    # folder is how the UI explains a thread it can never re-fetch.
+    folder: { type: :string },
+    customer_last_read_at: { type: :datetime },
+    customer_last_read_mid: { type: :string },
+    # Which app currently owns the thread. If the Page Inbox holds control, our
+    # Send API call fails — a send has to read this rather than discover it as
+    # an opaque API error.
+    thread_owner_app_id: { type: :string },
+    thread_control_at: { type: :datetime },
+    last_referral_ref: { type: :string },
+    # Any event at all, including ones that are not messages. Distinct from
+    # last_message_at so a quiet-but-active thread still sorts sensibly.
+    last_event_at: { type: :datetime }
+  }.freeze
+
+  def change
+    MESSAGE_COLUMNS.each do |name, options|
+      add_column :instagram_connect_messages, name, options[:type],
+                 **options.except(:type), if_not_exists: true
+    end
+
+    CONVERSATION_COLUMNS.each do |name, options|
+      add_column :instagram_connect_conversations, name, options[:type],
+                 **options.except(:type), if_not_exists: true
+    end
+
+    add_index :instagram_connect_messages, :sent_at, if_not_exists: true
+    add_index :instagram_connect_messages, :reply_to_mid, if_not_exists: true
+
+    reversible do |dir|
+      dir.up { backfill_sent_at }
+    end
+  end
+
+  private
+
+  # Existing rows predate the column and every ordering now reads it. Rather
+  # than leave them NULL and make every query COALESCE, seed them with the only
+  # timestamp we have.
+  def backfill_sent_at
+    execute(<<~SQL.squish)
+      UPDATE instagram_connect_messages
+      SET sent_at = created_at
+      WHERE sent_at IS NULL
+    SQL
+  end
+end

data/db/migrate/20260725200250_create_instagram_connect_message_reactions.rb

@@ -0,0 +1,30 @@
+class CreateInstagramConnectMessageReactions < ActiveRecord::Migration[7.1]
+  # An append-only log of reactions, not a current-state table.
+  #
+  # Meta guarantees no ordering across webhook batches, so react → unreact →
+  # react can arrive in any sequence. Storing each event and reading the latest
+  # by reacted_at self-corrects; storing "the" reaction on the message would
+  # let a late unreact clear a reaction the customer has since re-added.
+  def change
+    create_table :instagram_connect_message_reactions, if_not_exists: true do |t|
+      t.bigint :conversation_id, null: false
+      # Nullable: a reaction can arrive before the message it belongs to, and
+      # can point at a message that predates this install entirely.
+      t.bigint :message_id
+      t.string :ig_message_id, null: false
+      t.string :igsid, null: false
+      t.string :actor, null: false
+      t.string :action, null: false
+      t.string :reaction
+      t.string :emoji
+      t.datetime :reacted_at, null: false
+      t.timestamps
+    end
+
+    add_index :instagram_connect_message_reactions, [ :conversation_id, :reacted_at ],
+              name: "index_instagram_connect_reactions_on_conversation_and_time",
+              if_not_exists: true
+    add_index :instagram_connect_message_reactions, :ig_message_id, if_not_exists: true
+    add_index :instagram_connect_message_reactions, :message_id, if_not_exists: true
+  end
+end

data/db/migrate/20260725201320_create_instagram_connect_message_attachments.rb

@@ -0,0 +1,33 @@
+class CreateInstagramConnectMessageAttachments < ActiveRecord::Migration[7.1]
+  # One row per file on a message, rather than the single set of media_* columns
+  # the messages table already carries.
+  #
+  # A DM can hold up to ten images, and each one fetches independently: one job
+  # per attachment means a ten-image message does not serialise behind the
+  # slowest file, and a retry ladder isolates to the file that actually failed.
+  def change
+    create_table :instagram_connect_message_attachments, if_not_exists: true do |t|
+      t.bigint :message_id, null: false
+      t.integer :position, null: false
+      t.string :kind, null: false
+      # Meta's CDN URL. Short-lived and not re-requestable, which is why the
+      # bytes are copied into the host's own storage rather than linked.
+      t.text :source_url
+      t.string :state, null: false, default: "pending"
+      t.string :mime
+      t.string :filename
+      t.bigint :size
+      t.string :error
+      # A reusable id from Meta's Attachment Upload API, so a canned reply image
+      # is uploaded once and sent by reference thereafter.
+      t.string :ig_attachment_id
+      t.timestamps
+    end
+
+    add_index :instagram_connect_message_attachments, [ :message_id, :position ],
+              unique: true, if_not_exists: true
+    add_index :instagram_connect_message_attachments, [ :state, :created_at ],
+              name: "index_instagram_connect_attachments_on_state_and_time",
+              if_not_exists: true
+  end
+end

data/db/migrate/20260725202616_add_outbound_send_fields.rb

@@ -0,0 +1,27 @@
+class AddOutboundSendFields < ActiveRecord::Migration[7.1]
+  # Individual add_column calls rather than a bulk change_table: only add_column
+  # honours if_not_exists, and every migration this gem ships has to survive
+  # being re-run against a database that already has the columns.
+  COLUMNS = {
+    # A message over Meta's 1000-byte ceiling goes out as several sends. This
+    # is the resume cursor, so a worker killed mid-fan-out picks up where it
+    # stopped instead of repeating parts the customer already received.
+    delivered_parts_count: { type: :integer, default: 0, null: false },
+    # The reusable id Meta returns from the Attachment Upload API, so a canned
+    # reply image is uploaded once and sent by reference afterwards.
+    attachment_upload_id: { type: :string }
+  }.freeze
+
+  def change
+    COLUMNS.each do |name, options|
+      add_column :instagram_connect_messages, name, options[:type],
+                 **options.except(:type), if_not_exists: true
+    end
+
+    # Composer idempotency: a double-submit carries the same token and the
+    # unique index turns the second one into a no-op rather than a second
+    # bubble the customer sees twice.
+    add_column :instagram_connect_messages, :client_token, :string, if_not_exists: true
+    add_index :instagram_connect_messages, :client_token, unique: true, if_not_exists: true
+  end
+end

data/db/migrate/20260725203213_create_instagram_connect_media.rb

@@ -0,0 +1,30 @@
+class CreateInstagramConnectMedia < ActiveRecord::Migration[7.1]
+  # Our own record of the account's posts, reels and stories.
+  #
+  # It exists because insights and mentions both need something to hang off, and
+  # because a story is gone from the API 24 hours after it is posted — the row
+  # has to outlive the thing it describes.
+  def change
+    create_table :instagram_connect_media, if_not_exists: true do |t|
+      t.bigint :account_id, null: false
+      t.string :ig_media_id, null: false
+      t.string :media_type
+      # FEED | STORY | REELS | AD. Distinct from media_type, and the field that
+      # decides which insight metrics Meta will even accept.
+      t.string :media_product_type
+      t.text :caption
+      t.text :permalink
+      t.text :media_url
+      t.text :thumbnail_url
+      t.datetime :posted_at
+      t.integer :comments_count
+      t.integer :like_count
+      t.datetime :synced_at
+      t.timestamps
+    end
+
+    add_index :instagram_connect_media, [ :account_id, :ig_media_id ],
+              unique: true, if_not_exists: true
+    add_index :instagram_connect_media, [ :account_id, :posted_at ], if_not_exists: true
+  end
+end

data/db/migrate/20260725203214_create_instagram_connect_mentions.rb

@@ -0,0 +1,30 @@
+class CreateInstagramConnectMentions < ActiveRecord::Migration[7.1]
+  # Every @mention of the account — in a comment, in a caption, or as a tag.
+  #
+  # This is a table rather than a query because **Meta does not store mention
+  # notifications**. There is no endpoint to ask "what did I miss": the webhook
+  # is delivered once and if it is not written down at that moment it is gone.
+  # For a travel brand these are the highest-value events on the platform —
+  # customers posting photos of a trip we sold them.
+  def change
+    create_table :instagram_connect_mentions, if_not_exists: true do |t|
+      t.bigint :account_id, null: false
+      t.string :kind, null: false
+      t.string :ig_media_id
+      t.string :comment_id
+      t.bigint :message_id
+      t.string :from_username
+      t.text :text
+      t.text :permalink
+      t.datetime :mentioned_at, null: false
+      t.datetime :replied_at
+      t.string :reply_comment_id
+      t.timestamps
+    end
+
+    add_index :instagram_connect_mentions, [ :account_id, :kind, :ig_media_id, :comment_id ],
+              unique: true, name: "index_instagram_connect_mentions_unique", if_not_exists: true
+    add_index :instagram_connect_mentions, [ :account_id, :mentioned_at ],
+              name: "index_instagram_connect_mentions_on_account_and_time", if_not_exists: true
+  end
+end