instagram_connect 0.2.0 → 0.3.0

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

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` |