instagram_connect 0.2.1 → 0.3.1

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

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,58 @@ module InstagramConnect
       get("/me/accounts", { fields: "id,name,access_token,instagram_business_account" })
     end
 
+    # One Page by id. /me/accounts answers for the Pages a token may *enumerate*;
+    # this answers for a Page it may *read*. Those are not the same set — a Page
+    # granted through the Login-for-Business asset picker is readable here while
+    # absent from the listing.
+    def page(page_id)
+      get("/#{page_id}", { fields: "id,name,access_token,instagram_business_account" })
+    end
+
+    # The asset ids this token actually carries, from Meta's own record of the
+    # consent. Needs no permission beyond the app's own credentials.
+    def granted_asset_ids
+      result = get("/debug_token", { input_token: access_token,
+                                     access_token: "#{config.app_id}|#{config.app_secret}" })
+      return [] unless result.success?
+
+      Array(result.data.dig("data", "granular_scopes"))
+        .flat_map { |scope| Array(scope["target_ids"]) }
+        .uniq
+    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 +249,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 +267,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/connect.rb

@@ -35,11 +35,34 @@ module InstagramConnect
     def resolve_identity(data)
       return { ig_user_id: data[:ig_user_id], page_id: data[:page_id] } if data[:ig_user_id]
 
-      result = Client.new(access_token: data[:access_token], config: @config).list_pages
-      page = Array(result.data["data"]).find { |p| p["instagram_business_account"] }
-      raise ConfigurationError, "no Instagram business account is linked to a Page" unless page
+      client = Client.new(access_token: data[:access_token], config: @config)
+      page = candidate_pages(client).find { |p| p["instagram_business_account"] }
+      unless page
+        raise ConfigurationError,
+          "connected, but no Page with a linked Instagram business account was found — " \
+          "checked the Pages this token can list and the assets it was granted"
+      end
 
-      { ig_user_id: page.dig("instagram_business_account", "id"), page_id: page["id"] }
+      { ig_user_id: page.dig("instagram_business_account", "id").to_s, page_id: page["id"].to_s }
+    end
+
+    # /me/accounts lists only the Pages a token may enumerate, and a Page granted
+    # through the Login-for-Business asset picker is not one of them — the list
+    # comes back empty while the Page itself reads fine. So when the listing has
+    # nothing usable, ask the token which assets it carries and read those.
+    def candidate_pages(client)
+      listed = client.list_pages
+      unless listed.success?
+        raise ApiError, "could not read Pages from Instagram: #{listed.error_message}"
+      end
+
+      pages = Array(listed.data["data"])
+      return pages if pages.any? { |p| p["instagram_business_account"] }
+
+      client.granted_asset_ids.filter_map do |id|
+        result = client.page(id)
+        result.data if result.success?
+      end
     end
   end
 end