instagram_connect 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afc5d08b4207b0268104bbf7a4955406b26298e4da4406bd5034a93b8a43982f
-  data.tar.gz: 4d436bf9a398fc745f4a594b1346cd8315a949391213f83c45cc52c07694e993
+  metadata.gz: bfea76e8f86d1da429ba916fdf03124bb3eb0a4f0cc8d50bdeb5db838282026a
+  data.tar.gz: b55274a8583dcad12bedca7025517fbfcea36865479f28c520c7c103e8e4d49a
 SHA512:
-  metadata.gz: 3d4894411aa0ad5924a8d4d163215a880e8344aa3306a814400cd73e2ad717d5bca7f4a4284c4baa81162af98cabc987983c4715c3eaab8b0fb16ba9a69321ec
-  data.tar.gz: 9ce313d2dd27ce96e913da61d46eb9f4e87bcbac7681fcd6963447759286b6419a7453d50821d9909fe570eca0fe98b5620fc709ead569e4f8c88f3752b635c9
+  metadata.gz: b9d2f5d664868d9444883e603684bf22e65880d8e75ef65d6014c14a7a6065cdf5d199b1d77c6c3c2f3178c7c804ebc921cdf08966d6c68b2ee18686a1c3a3f4
+  data.tar.gz: d21363ec67aa080df5ff76747cf6f97db0b81963fe66716e7df44e44456dab3cf5b528e502f43c441a967a8d029459d2bb1dcef343b215979524bcc9c068bbbe

data/.github/workflows/ci.yml

@@ -39,3 +39,39 @@ jobs:
 
       - name: Run tests
         run: bundle exec rspec --format progress
+
+  # The gem ships its own migrations into whatever database the host runs, and
+  # most hosts run Postgres. The SQLite job above is the fast default so a
+  # contributor needs no services; this one is what stops adapter-specific DDL
+  # in db/migrate from reaching an adopter's deploy unnoticed.
+  test-postgres:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Run tests against Postgres
+        env:
+          PGPASSWORD: postgres
+          INSTAGRAM_CONNECT_TEST_DATABASE_URL: postgresql://postgres:postgres@localhost:5432/instagram_connect_test
+        run: |
+          createdb -h localhost -U postgres instagram_connect_test
+          bundle exec rspec --format progress

data/CHANGELOG.md

@@ -4,6 +4,95 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/) and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.3.0] - 2026-07-26
+
+Conversations and engagement. The gem parsed 2 of the 15 webhook fields Meta can
+send on the `instagram` object; it now parses 12 and durably banks the rest.
+
+### Added
+- **Webhook event ledger.** Every event is written to
+  `instagram_connect_webhook_events` verbatim before anything parses it. Meta
+  neither stores webhook notifications nor re-delivers them, so a parse bug used
+  to be permanent data loss and is now a re-runnable row. `ReplayEventsJob`
+  re-runs banked events once a handler exists, which also means a field can be
+  subscribed at Meta before the gem can parse it.
+- **Handlers** for `message_reactions`, `messaging_seen`, `messaging_referral`,
+  `messaging_optins`, `messaging_handover`, `mentions` and `story_insights`,
+  alongside the existing messages, echoes, postbacks and comments.
+- **Inbound media.** Attachments get a row each and one fetch job apiece; bytes
+  are copied into the host's storage with a magic-byte MIME sniff that overrides
+  the declared Content-Type. Requires Active Storage in the host, and no-ops
+  without it.
+- **Outbound media** via Meta's Attachment Upload API, which moves bytes over an
+  authenticated POST rather than exposing a signed URL to a customer's file.
+- `TextSplitter`, which splits replies over Meta's 1000-**byte** message ceiling
+  rather than letting the send be rejected whole.
+- Sender actions, quick replies, generic templates, private replies, ice
+  breakers and the persistent menu on the client.
+- **Per-account tokens.** `page_access_token` is now its own encrypted column;
+  `Account#client` is the only place a client is built and pins the config to
+  the account's own auth path.
+- `AccountReadinessJob`, moved in from host applications. It swaps the OAuth
+  user token for the Page token and subscribes the Page to the webhook fields
+  the ingest registry can actually parse.
+- **Cursor pagination** (`Client#collect`, `#each_page`) and **rate budgets**
+  (`RateLimiter`, `instagram_connect_api_budgets`), driven by Meta's own
+  `X-Business-Use-Case-Usage` header rather than by local arithmetic.
+- `ProfileSyncJob`, filling the `username` and `display_name` columns that had
+  existed since 0.1 with nothing ever writing them.
+- `MediaItem`, `Mention`, `InsightSnapshot`, `MessageAttachment`,
+  `MessageReaction`, `WebhookEvent` and `ApiBudget` models, with migrations.
+
+### Changed
+- Messages carry `sent_at`, Meta's own clock. Thread ordering used our
+  `created_at`, so a webhook batch delayed by a redeploy silently reordered a
+  conversation. Every `Conversation` writer is now monotonic.
+- Uniqueness is scoped per account. A global unique index on `ig_message_id`
+  dropped messages outright when two connected accounts messaged each other.
+- An attachment arriving with no URL no longer marks the message media
+  `pending`. Instagram CDN links expire and cannot be re-requested, so that left
+  a loading placeholder that would never resolve.
+- `Ingest.call` returns a `Summary` rather than a plain Hash. It reads as the
+  old hash — `skipped` still reports duplicates plus unhandled — and adds
+  `duplicates`, `unhandled`, `failed` and `callback_errors`.
+- Host callbacks fire outside the handler in their own rescue. The rows are
+  committed by then, so a raising hook no longer marks the event failed and
+  cause it to be replayed and duplicated.
+
+### Deprecated
+- `InboundMessage`. `WebhookEvent` is the dedupe claim now: keying every event
+  type on one message id is wrong once `messaging_seen` carries the mid of a
+  message already claimed. Kept in step for 0.2.x hosts; removal at 1.0.
+
+### Fixed
+- Every `Client` was built from the globally configured auth path, so a host
+  with accounts on both paths talked to the wrong Graph host — silently.
+- `refresh_access_token!` refreshed via the global strategy rather than the
+  account's own.
+
+
+### Documentation
+- Rewrote the README with a badge row, table of contents, a quick start, and a
+  usage section per feature (webhooks and signature verification, the messaging
+  window, comment moderation, publishing, the Graph client, background jobs, the
+  UI and theming, and the CLI).
+- Added `docs/CONFIGURATION.md`, a full reference for every `Configuration`
+  setting with its type, default, and environment-variable fallback.
+- Added `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1), and
+  `SECURITY.md`.
+- Removed the duplicate `MIT-LICENSE` file, keeping `LICENSE.txt` as the single
+  license, and updated the gemspec `files` list to match.
+
+## [0.2.1]
+
+### Fixed
+- Migrations are now idempotent (`create_table` / `add_index` with `if_not_exists: true`),
+  so `db:migrate` / `db:prepare` succeeds on a database that already has the tables —
+  e.g. an existing deploy, or one set up via `db:schema:load`. Previously a redeploy
+  could fail with `PG::DuplicateTable`.
+
 ## [0.2.0]
 
 True plug-and-play: the gem now owns the data model and the UI, so a host adds

data/Gemfile

@@ -6,6 +6,10 @@ gemspec
 gem "puma"
 
 gem "sqlite3"
+# The suite runs on SQLite by default so a contributor needs no services, and on
+# Postgres in CI so adapter-specific DDL in db/migrate cannot reach an adopter
+# unnoticed. See INSTAGRAM_CONNECT_TEST_DATABASE_URL in spec/rails_helper.rb.
+gem "pg"
 gem "rack-test"
 gem "webmock"
 gem "rspec-rails", "~> 8.0"

data/README.md

@@ -1,63 +1,116 @@
 # instagram_connect
 
-A mountable Rails engine that connects your app to **Instagram** over the official
-**Meta Graph API** — receive and reply to DMs and comments in real time via
-HMAC-verified webhooks, publish posts, and manage OAuth tokens. Official API only:
-no reverse-engineered automation, no browser bots, so your account stays safe.
+Instagram DMs, comments, and publishing for Rails, over the official Meta Graph API.
 
+[![Gem Version](https://img.shields.io/gem/v/instagram_connect.svg)](https://rubygems.org/gems/instagram_connect)
 [![CI](https://github.com/kshtzkr/instagram_connect/actions/workflows/ci.yml/badge.svg)](https://github.com/kshtzkr/instagram_connect/actions/workflows/ci.yml)
-
-## Why official-only
-
-Instagram permanently disables real accounts that use reverse-engineered/private-API
-automation, and appeals rarely succeed — you lose the handle, followers, and DM
-history at once. Unlike WhatsApp (where a ban costs a replaceable phone number), an
-Instagram ban costs the whole brand account. This gem only ever speaks the sanctioned
-Graph API.
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-CC342D.svg)](https://www.ruby-lang.org)
+
+`instagram_connect` is a mountable Rails engine that connects your app to an
+Instagram professional account. You can receive and reply to DMs and comments in
+real time through HMAC-verified webhooks, publish image posts, and manage OAuth
+tokens. It speaks only the sanctioned Meta Graph API (Instagram Login or Facebook
+Login) — there is no reverse-engineered automation or browser scripting involved.
+
+That distinction matters: Instagram disables accounts that use private-API
+automation, and an appeal rarely restores the handle, followers, or DM history.
+Using the official API keeps the account in good standing.
+
+## Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+- [Connecting an account](#connecting-an-account)
+- [Webhooks](#webhooks)
+- [Replying to DMs and the messaging window](#replying-to-dms-and-the-messaging-window)
+- [Moderating comments](#moderating-comments)
+- [Publishing](#publishing)
+- [Using the Graph client directly](#using-the-graph-client-directly)
+- [Background jobs](#background-jobs)
+- [The inbox UI and theming](#the-inbox-ui-and-theming)
+- [CLI](#cli)
+- [Data model](#data-model)
+- [Auth paths](#auth-paths)
+- [Meta App Review](#meta-app-review)
+- [Meta platform constraints](#meta-platform-constraints)
+- [Testing](#testing)
+- [Development](#development)
+- [Contributing](#contributing)
+- [Security](#security)
+- [Versioning](#versioning)
+- [License](#license)
 
 ## Features
 
-- **DMs** — receive inbound messages in real time (webhooks), reply with text within
-  Meta's 24-hour window (extended to 7 days via the human-agent tag).
-- **Comments** — read, reply to, hide/unhide, and delete comments on your posts.
-- **Publishing** — publish image posts (Reels/video/carousel are on the roadmap).
-- **Two auth paths** — `:instagram_login` (no Facebook Page) or `:facebook_login`
-  (linked Page + durable tokens), selected by config. See
+- DMs: receive inbound messages in real time through webhooks, and reply with
+  text inside Meta's 24-hour window (extended to 7 days with the human-agent tag).
+- Comments: read, reply to, hide, unhide, and delete comments on your media.
+- Publishing: publish image posts. Reels, video, and carousel are on the roadmap.
+- Two auth paths: `:instagram_login` (no Facebook Page) or `:facebook_login`
+  (linked Page and durable tokens), selected by configuration. See
   [docs/auth_paths.md](docs/auth_paths.md).
-- **Mounted inbox UI** — a ready inbox, comment moderation, and publish screens you
-  can restyle to your own design system.
-- **Secure by default** — encrypted tokens at rest, HMAC-verified webhooks.
+- A mounted UI: a DM inbox, comment moderation, and a publish screen, rendered in
+  the engine's own layout and themeable from the initializer.
+- Encrypted tokens at rest and HMAC-verified webhooks.
 
 ## Requirements
 
-- Rails ≥ 7.1, Ruby ≥ 3.1
-- Active Storage (media attachments — roadmap) and an Active Job backend
-  (Solid Queue, Sidekiq, …) for webhook ingestion + token refresh
-- Active Record Encryption configured for token storage
-  (`bin/rails db:encryption:init`), or set `config.encrypt_tokens = false`
-- An Instagram **professional** account (Business or Creator)
+- Ruby >= 3.1
+- Rails >= 7.1
+- An Active Job backend (Solid Queue, Sidekiq, and so on). Webhook ingestion,
+  outbound sends, and token refresh all run as jobs.
+- Active Record Encryption configured (`bin/rails db:encryption:init`) for token
+  storage, or set `config.encrypt_tokens = false` if your app has no encryption.
+- A Meta app with an Instagram **professional** account (Business or Creator) and
+  either Instagram Login or Facebook Login set up. See
+  [docs/auth_paths.md](docs/auth_paths.md).
 
 ## Installation
 
+Add the gem:
+
 ```ruby
 # Gemfile
 gem "instagram_connect"
 ```
 
+Then install and migrate:
+
 ```bash
 bundle install
-bin/rails g instagram_connect:install   # writes the initializer + mounts the engine
-bin/rails db:migrate                    # runs the gem's migrations in place
+bin/rails g instagram_connect:install   # writes the initializer and mounts the engine
+bin/rails db:migrate                     # runs the gem's migrations in place
 ```
 
-The install generator writes `config/initializers/instagram_connect.rb` and mounts
-the engine at `/instagram`. **Migrations ship inside the gem and run in place** —
-nothing is copied into your app, so every adopter gets exactly the same schema,
-versioned with the gem. That's the whole install: **configuration only, no copied
-migrations, views, or CSS.**
+The install generator writes `config/initializers/instagram_connect.rb` and adds
+`mount InstagramConnect::Engine => "/instagram"` to your routes. Migrations ship
+inside the gem and run in place, so nothing is copied into your app and every
+adopter gets the same schema, versioned with the gem. Configuration is the only
+thing you add.
+
+## Quick start
+
+1. Fill in the initializer with your Meta app credentials (see
+   [Configuration](#configuration)).
+2. Point your Meta app's webhook at `https://<your-host>/instagram/webhooks` with
+   the same `verify_token` (see [Webhooks](#webhooks)).
+3. Send an operator to `GET /instagram/oauth/start` to connect the account.
+4. Open `/instagram` for the inbox.
+
+Check that the credentials are in place before you start:
+
+```bash
+bundle exec instagram_connect doctor
+```
 
 ## Configuration
 
+The initializer covers the settings most apps need:
+
 ```ruby
 # config/initializers/instagram_connect.rb
 InstagramConnect.configure do |config|
@@ -71,7 +124,7 @@ InstagramConnect.configure do |config|
   config.parent_controller = "ApplicationController"
   config.authenticate_with = -> { authenticate_user! }          # runs in controller context
   config.current_user_id_resolver = -> { current_user&.id }     # attributes replies
-  config.after_connect_redirect = "/instagram"
+  config.after_connect_redirect = "/instagram/conversations"
 
   # Optional host hooks
   config.on_message = ->(message) { NotifyOpsJob.perform_later(message.id) }
@@ -79,36 +132,174 @@ InstagramConnect.configure do |config|
 end
 ```
 
+Every setting, with its type, default, and environment-variable fallback, is
+documented in [docs/CONFIGURATION.md](docs/CONFIGURATION.md). Secrets can come
+from the environment instead of the initializer:
+`INSTAGRAM_CONNECT_APP_ID`, `INSTAGRAM_CONNECT_APP_SECRET`,
+`INSTAGRAM_CONNECT_VERIFY_TOKEN`, and others.
+
 ## Connecting an account
 
-Send an operator to `GET /instagram/oauth/start`. They authorize with Meta and are
-redirected back to `config.after_connect_redirect` with a stored, encrypted
-`InstagramConnect::Account`. Schedule the refresh job daily so tokens stay fresh:
+Send an operator to `GET /instagram/oauth/start`. The engine redirects them to
+Meta's login dialog with a CSRF `state`, and Meta returns to
+`GET /instagram/oauth/callback`. The callback exchanges the code for a
+long-lived token and stores an `InstagramConnect::Account`, then redirects to
+`config.after_connect_redirect`.
+
+For the Facebook Login path the engine reads the Instagram business account
+linked to the operator's Page to resolve the account identity. For the Instagram
+Login path the identity comes back directly from the token exchange.
+
+Meta enforces an exact-match redirect URI. If the engine's own callback URL does
+not match what you registered, pin it with `config.redirect_uri`.
+
+## Webhooks
+
+Register `https://<your-host>/instagram/webhooks` as the callback URL in your
+Meta app and set the verify token to match `config.verify_token`. Subscribe the
+fields you need: `messages`, `messaging_postbacks`, `comments`, `mentions`. Meta
+must reach the URL publicly, so use a staging host or a tunnel during
+development; localhost will not receive callbacks.
+
+Two things happen at that path:
+
+- **Verification handshake (GET).** Meta sends `hub.mode=subscribe`, a
+  `hub.verify_token`, and a `hub.challenge`. The controller confirms the token
+  matches `config.verify_token` and echoes the challenge back, otherwise it
+  responds `403`.
+- **Event delivery (POST).** Every delivery carries an `X-Hub-Signature-256`
+  header: the HMAC-SHA256 of the raw request body keyed by your `app_secret`.
+  `InstagramConnect::SignatureVerifier` recomputes it and compares in constant
+  time. A bad or missing signature is rejected with `401`. The webhook controller
+  inherits `ActionController::Base` directly (not your host controller), so it
+  bypasses session auth and CSRF and authenticates only by this HMAC.
+
+A verified POST is acknowledged immediately and handed to
+`InstagramConnect::IngestJob`, so Meta gets a fast `200`.
+`InstagramConnect::Ingest` then walks the payload:
+
+- **Messages** are deduped on Meta's message id through the
+  `InstagramConnect::InboundMessage` ledger (so a redelivery is not processed
+  twice), stored as `Message` rows on the right `Conversation`, and inbound
+  messages fire `config.on_message`. Echoes of your own outbound sends are
+  stored as outbound but do not fire the hook.
+- **Comments** are upserted by comment id into `Comment` and fire
+  `config.on_comment`.
+- **Postbacks** fire `config.on_postback` with
+  `{ account_id:, sender_id:, payload:, title: }`.
+
+The engine also adds `access_token`, `app_secret`, `verify_token`, and
+`hub_verify_token` to Rails' filtered parameters, so they do not appear in logs.
+
+## Replying to DMs and the messaging window
+
+The inbox composer creates an outbound `Message` in the `pending` state and
+enqueues `InstagramConnect::SendMessageJob`. The job claims the row with an
+atomic update (so a duplicate enqueue cannot double-send) and then checks Meta's
+messaging window before it sends.
+
+`InstagramConnect::MessagingWindow` encodes the rule. Measuring from the user's
+last inbound message:
+
+- within 24 hours: `:standard`, sent with no tag.
+- 24 hours to 7 days: `:human_agent`, sent with the `HUMAN_AGENT` tag (human
+  replies only).
+- past 7 days, or the user has never messaged: `:closed`, nothing may be sent.
+
+When the window is closed the job marks the message `failed` with reason
+`outside_messaging_window` rather than calling the API. You can check the state
+yourself:
 
 ```ruby
-# config/recurring.yml (Solid Queue), or your scheduler of choice
-instagram_connect_token_refresh:
-  class: InstagramConnect::RefreshTokensJob
-  schedule: every day at 3am
+window = InstagramConnect::MessagingWindow.new(last_inbound_at: conversation.last_inbound_at)
+window.open?      # => true / false
+window.state      # => :standard, :human_agent, or :closed
+window.send_tag   # => nil, "HUMAN_AGENT", or :blocked
 ```
 
-## Webhooks
+## Moderating comments
+
+The mounted `/instagram/comments` screen lists recorded comments and moderates
+them. Moderation calls the Graph API synchronously and updates local state only
+on success. The same operations are available on the client:
+
+```ruby
+client = InstagramConnect::Client.new(access_token: account.access_token, ig_user_id: account.ig_user_id)
+client.reply_comment(comment_id: id, text: "Thanks!")
+client.hide_comment(comment_id: id, hidden: true)
+client.delete_comment(comment_id: id)
+client.list_comments(media_id: media_id)
+```
+
+## Publishing
+
+Publishing an image is a two-step Graph flow: create a media container from a
+public HTTPS image URL, then publish it. The mounted `/instagram/posts` screen
+does this, and the client exposes each step:
+
+```ruby
+client = InstagramConnect::Client.new(access_token: account.access_token, ig_user_id: account.ig_user_id)
+
+container = client.create_media_container(image_url: "https://example.com/photo.jpg", caption: "Hello")
+published = client.publish_media(creation_id: container.id) if container.success?
+
+client.publishing_limit   # remaining quota in the rolling 24-hour window
+```
 
-Point your Meta app's webhook at `https://<your-host>/instagram/webhooks` and use the
-same `verify_token` you configured. Subscribe the fields you need: `messages`,
-`messaging_postbacks`, `comments`, `mentions`. The engine verifies the
-`X-Hub-Signature-256` HMAC on every delivery and ingests off the request path.
+## Using the Graph client directly
 
-## The inbox UI
+`InstagramConnect::Client` is a thin wrapper over the Graph API, bound to one
+account's access token. Every call returns an `InstagramConnect::Result` rather
+than raising on an API error, so callers branch on `success?`:
 
-Mounted at `/instagram`: a self-contained, self-styled DM inbox (window-aware reply
-composer), comment moderation, and publishing — its own chrome, like an admin engine.
-Nothing to build in your app.
+```ruby
+client = InstagramConnect::Client.new(access_token: account.access_token, ig_user_id: account.ig_user_id)
+
+result = client.send_text(recipient_id: igsid, text: "Hi there")
+if result.success?
+  result.id            # Meta's message id
+else
+  result.error_message # human-readable message from Meta
+  result.error_code    # Meta's application-level code
+  result.retry_after   # rate-limit hint, when present
+end
+```
+
+Other client methods include `send_media`, `send_reaction`, `private_reply`,
+`list_media`, `media_insights`, `profile`, and `list_pages`. Transport and
+programming errors still raise; only API-level failures come back as a failed
+`Result`.
+
+## Background jobs
+
+Three jobs do the asynchronous work. All use Active Job, so they run on whatever
+backend your app configures.
+
+- `InstagramConnect::IngestJob` — persists a verified webhook payload off the
+  request path.
+- `InstagramConnect::SendMessageJob` — sends one pending outbound message exactly
+  once, enforcing the messaging window.
+- `InstagramConnect::RefreshTokensJob` — refreshes tokens for active accounts
+  before they expire. One account's failure does not abort the batch, and
+  accounts on the Facebook Login path (non-expiring tokens) are a no-op. Schedule
+  it daily:
+
+  ```yaml
+  # config/recurring.yml (Solid Queue), or your scheduler of choice
+  instagram_connect_token_refresh:
+    class: InstagramConnect::RefreshTokensJob
+    schedule: every day at 3am
+  ```
 
-### Theming
+## The inbox UI and theming
 
-Tint the whole UI to your brand from the initializer — no CSS or view files in your
-app. Any subset of keys is merged over the gem defaults:
+Mounted at `/instagram`: a DM inbox with a window-aware reply composer, comment
+moderation, and an image publish screen. By default the engine renders in its own
+bundled layout and stylesheet (`inherit_host_layout` is `false`), like an admin
+engine, so there is nothing to build in your app.
+
+Tint the whole UI from the initializer. Any subset of theme keys is merged over
+the defaults, with no CSS or view files in your app:
 
 ```ruby
 config.theme = {
@@ -118,48 +309,112 @@ config.theme = {
 }
 ```
 
-Deeper control (optional): render inside your own layout with
-`config.inherit_host_layout = true` (then add `<%= instagram_connect_styles %>` to
-your `<head>`), or copy the views/controllers to fully override them:
+The full list of theme keys and their defaults is in
+[docs/CONFIGURATION.md](docs/CONFIGURATION.md#theme).
+
+For deeper control, render inside your own layout with
+`config.inherit_host_layout = true` and add `<%= instagram_connect_styles %>` to
+your `<head>`, or copy the views and controllers into your app to override them:
 
 ```bash
 bin/rails g instagram_connect:views        # copy views into app/views/instagram_connect
-bin/rails g instagram_connect:controllers  # copy controllers to override
+bin/rails g instagram_connect:controllers  # copy controllers to override the engine's
 ```
 
 ## CLI
 
+The gem installs an `instagram_connect` executable with a `doctor` command that
+checks the configuration:
+
 ```bash
-bundle exec instagram_connect doctor   # preflight your configuration
+bundle exec instagram_connect doctor
 ```
 
+It reports `OK` or `MISSING` for each of: a valid `auth_path`, `app_id`,
+`app_secret`, and `verify_token`.
+
+## Data model
+
+The engine owns these tables (all prefixed `instagram_connect_`):
+
+- `Account` — a connected Instagram professional account, holding the encrypted
+  access token and the identity the client sends as.
+- `Conversation` — one DM thread between an account and an Instagram user
+  (`igsid`), with a denormalized unread count and last-message summary.
+- `Message` — one bubble in a thread, inbound or outbound, with direction,
+  status, kind, and source.
+- `InboundMessage` — a dedupe ledger keyed by Meta's message id.
+- `Comment` — a comment on the account's media, with moderation state.
+
+## Auth paths
+
+The gem supports both of Meta's integration paths, selected by
+`config.auth_path`. They differ in the Graph host, whether a Facebook Page is
+required, the OAuth scopes, and token lifetime.
+[docs/auth_paths.md](docs/auth_paths.md) covers the trade-offs and how to add a
+new path.
+
 ## Meta App Review
 
-Messaging real customers requires Advanced Access, which requires **App Review** and
-**Business Verification**. Until approved, you can only message accounts added as
-testers on your Meta app. The full checklist — permissions per auth path, privacy
-policy, screencasts, common rejection reasons — is in
+Messaging real customers requires Advanced Access, which requires App Review and
+Business Verification. Until you are approved, you can only message accounts you
+add as testers on your Meta app. The checklist — permissions per auth path,
+privacy policy, screencasts, and common rejection reasons — is in
 [docs/app_review_guide.md](docs/app_review_guide.md).
 
-## Constraints (Meta rules, not the gem's)
+## Meta platform constraints
 
-- **24-hour window**: you can only reply within 24h of the customer's last message
-  (7 days with the human-agent tag). The gem enforces this and blocks illegal sends.
-- **No cold DMs**: you can't message someone who never messaged you.
-- **Publishing**: 100 API-published posts per rolling 24h; media must be at a public
-  HTTPS URL.
+These are Meta's rules, enforced by the platform rather than the gem, but worth
+knowing up front:
+
+- 24-hour window: you can only reply within 24 hours of the customer's last
+  message (7 days with the human-agent tag). The gem enforces this and blocks
+  sends that would violate it.
+- No cold DMs: you cannot message someone who has never messaged you.
+- Publishing: a rolling limit of 100 API-published posts per 24 hours, and media
+  must be served from a public HTTPS URL.
 
 ## Testing
 
+The suite boots a small in-memory dummy Rails app that mounts the engine, runs
+against SQLite in memory, and stubs the Graph API with WebMock, so no database or
+network access is needed:
+
 ```bash
-bundle exec rspec      # in-memory sqlite, WebMock-stubbed Graph API, 100% coverage
+bundle exec rspec
 bundle exec rubocop
 ```
 
-## Roadmap
+Coverage is held to 100% line and branch on the gem's business-logic files.
+
+## Development
+
+```bash
+git clone https://github.com/kshtzkr/instagram_connect.git
+cd instagram_connect
+bundle install
+bundle exec rspec
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the branch and pull-request flow.
+
+## Contributing
+
+Bug reports and pull requests are welcome. Please read
+[CONTRIBUTING.md](CONTRIBUTING.md) and the
+[Code of Conduct](CODE_OF_CONDUCT.md). Contributions must pass CI (RSpec and
+RuboCop) and keep coverage at 100%.
+
+## Security
+
+Report vulnerabilities privately per [SECURITY.md](SECURITY.md). Please do not
+open a public issue for a security problem.
+
+## Versioning
 
-See [docs/roadmap.md](docs/roadmap.md) — next up: Turbo realtime broadcasting and
-Active Storage media (inbound fetch + outbound file send).
+This project follows [Semantic Versioning](https://semver.org/). Notable changes
+are recorded in [CHANGELOG.md](CHANGELOG.md), and releases are listed on the
+[GitHub releases page](https://github.com/kshtzkr/instagram_connect/releases).
 
 ## License
 

data/app/controllers/instagram_connect/comments_controller.rb

@@ -53,7 +53,7 @@ module InstagramConnect
 
     def client_for(comment)
       account = comment.account
-      Client.new(access_token: account.access_token, ig_user_id: account.ig_user_id)
+      account.client
     end
   end
 end