instagram_connect 0.1.0

data/lib/generators/instagram_connect/install/templates/instagram_connect.rb.tt

@@ -0,0 +1,35 @@
+InstagramConnect.configure do |config|
+  # Which Meta login path to use:
+  #   :instagram_login  — graph.instagram.com, no Facebook Page required
+  #   :facebook_login   — graph.facebook.com, requires a linked Facebook Page
+  config.auth_path = :instagram_login
+
+  config.app_id       = Rails.application.credentials.dig(:instagram_connect, :app_id) || ENV["INSTAGRAM_APP_ID"]
+  config.app_secret   = Rails.application.credentials.dig(:instagram_connect, :app_secret) || ENV["INSTAGRAM_APP_SECRET"]
+  config.verify_token = Rails.application.credentials.dig(:instagram_connect, :verify_token) || ENV["INSTAGRAM_VERIFY_TOKEN"]
+
+  # Pin the Graph API version.
+  config.graph_version = "v21.0"
+
+  # Rails integration.
+  config.parent_controller = "ApplicationController"
+
+  # Require operators to be signed in to use the inbox (runs in controller
+  # context — call your host auth here):
+  # config.authenticate_with = -> { authenticate_user! }
+
+  # Attribute outbound replies to the current operator:
+  # config.current_user_id_resolver = -> { current_user&.id }
+
+  # Where the OAuth callback returns after connecting an account.
+  config.after_connect_redirect = "/instagram"
+
+  # Optional host hooks — react to inbound events (notifications, AI, …):
+  # config.on_message = ->(message) { }
+  # config.on_comment = ->(comment) { }
+
+  # Access tokens are encrypted at rest via Active Record Encryption. Run
+  # `bin/rails db:encryption:init` once, or set this to false if your app has
+  # no encryption configured (tokens will be stored in plain text).
+  # config.encrypt_tokens = false
+end

data/lib/generators/instagram_connect/views_generator.rb

@@ -0,0 +1,16 @@
+require "rails/generators"
+
+module InstagramConnect
+  module Generators
+    # `rails g instagram_connect:views` — copy the engine's views into the host
+    # app so they can be restyled to the app's own design system.
+    class ViewsGenerator < ::Rails::Generators::Base
+      source_root InstagramConnect::Engine.root.join("app/views").to_s
+
+      def copy_views
+        directory "instagram_connect", "app/views/instagram_connect"
+        directory "layouts/instagram_connect", "app/views/layouts/instagram_connect"
+      end
+    end
+  end
+end

data/lib/instagram_connect/auth/facebook_login.rb

@@ -0,0 +1,68 @@
+module InstagramConnect
+  module Auth
+    # "Instagram API with Facebook Login" — talks to graph.facebook.com and
+    # requires the Instagram professional account be linked to a Facebook Page
+    # inside Business Manager. Long-lived Page / System-User tokens are durable
+    # (effectively non-expiring), so refresh is a no-op.
+    class FacebookLogin < Strategy
+      GRAPH = "https://graph.facebook.com".freeze
+      DIALOG = "https://www.facebook.com".freeze
+      DEFAULT_SCOPES = %w[
+        instagram_basic
+        instagram_manage_messages
+        instagram_manage_comments
+        instagram_content_publish
+        pages_show_list
+        pages_manage_metadata
+        pages_read_engagement
+      ].freeze
+
+      def graph_host
+        GRAPH
+      end
+
+      def scopes
+        DEFAULT_SCOPES
+      end
+
+      def authorize_url(redirect_uri:, state:)
+        query = {
+          client_id: app_id,
+          redirect_uri: redirect_uri,
+          scope: scopes.join(","),
+          response_type: "code",
+          state: state
+        }
+        "#{DIALOG}/#{graph_version}/dialog/oauth?#{URI.encode_www_form(query)}"
+      end
+
+      def exchange_code(code:, redirect_uri:)
+        short = HTTParty.get("#{GRAPH}/#{graph_version}/oauth/access_token", timeout: HTTP_TIMEOUT, query: {
+          client_id: app_id,
+          client_secret: app_secret,
+          redirect_uri: redirect_uri,
+          code: code
+        })
+        raise ApiError.new("code exchange failed: HTTP #{short.code}", status: short.code) unless short.success?
+        short_data = JSON.parse(short.body)
+
+        long = HTTParty.get("#{GRAPH}/#{graph_version}/oauth/access_token", timeout: HTTP_TIMEOUT, query: {
+          grant_type: "fb_exchange_token",
+          client_id: app_id,
+          client_secret: app_secret,
+          fb_exchange_token: short_data["access_token"]
+        })
+        raise ApiError.new("long-lived exchange failed: HTTP #{long.code}", status: long.code) unless long.success?
+        long_data = JSON.parse(long.body)
+
+        { access_token: long_data["access_token"], expires_at: expires_at_from(long_data["expires_in"]) }
+      end
+
+      # Long-lived Page / System-User tokens do not expire; return unchanged so
+      # the scheduled refresh job can treat every path uniformly.
+      def refresh_token(access_token:)
+        { access_token: access_token, expires_at: nil }
+      end
+    end
+  end
+end

data/lib/instagram_connect/auth/instagram_login.rb

@@ -0,0 +1,73 @@
+module InstagramConnect
+  module Auth
+    # "Instagram API with Instagram Login" — talks to graph.instagram.com and
+    # needs NO linked Facebook Page. Tokens are 60-day, refreshable. This is
+    # Meta's recommended path for new integrations.
+    class InstagramLogin < Strategy
+      AUTHORIZE_URL = "https://www.instagram.com/oauth/authorize".freeze
+      TOKEN_URL = "https://api.instagram.com/oauth/access_token".freeze
+      GRAPH = "https://graph.instagram.com".freeze
+      DEFAULT_SCOPES = %w[
+        instagram_business_basic
+        instagram_business_manage_messages
+        instagram_business_manage_comments
+        instagram_business_content_publish
+      ].freeze
+
+      def graph_host
+        GRAPH
+      end
+
+      def scopes
+        DEFAULT_SCOPES
+      end
+
+      def authorize_url(redirect_uri:, state:)
+        query = {
+          client_id: app_id,
+          redirect_uri: redirect_uri,
+          scope: scopes.join(","),
+          response_type: "code",
+          state: state
+        }
+        "#{AUTHORIZE_URL}?#{URI.encode_www_form(query)}"
+      end
+
+      def exchange_code(code:, redirect_uri:)
+        short = HTTParty.post(TOKEN_URL, timeout: HTTP_TIMEOUT, body: {
+          client_id: app_id,
+          client_secret: app_secret,
+          grant_type: "authorization_code",
+          redirect_uri: redirect_uri,
+          code: code
+        })
+        raise ApiError.new("code exchange failed: HTTP #{short.code}", status: short.code) unless short.success?
+        short_data = JSON.parse(short.body)
+
+        long = HTTParty.get("#{GRAPH}/access_token", timeout: HTTP_TIMEOUT, query: {
+          grant_type: "ig_exchange_token",
+          client_secret: app_secret,
+          access_token: short_data["access_token"]
+        })
+        raise ApiError.new("long-lived exchange failed: HTTP #{long.code}", status: long.code) unless long.success?
+        long_data = JSON.parse(long.body)
+
+        {
+          access_token: long_data["access_token"],
+          expires_at: expires_at_from(long_data["expires_in"]),
+          ig_user_id: short_data["user_id"]&.to_s
+        }
+      end
+
+      def refresh_token(access_token:)
+        resp = HTTParty.get("#{GRAPH}/refresh_access_token", timeout: HTTP_TIMEOUT, query: {
+          grant_type: "ig_refresh_token",
+          access_token: access_token
+        })
+        raise ApiError.new("token refresh failed: HTTP #{resp.code}", status: resp.code) unless resp.success?
+        data = JSON.parse(resp.body)
+        { access_token: data["access_token"], expires_at: expires_at_from(data["expires_in"]) }
+      end
+    end
+  end
+end

data/lib/instagram_connect/auth/strategy.rb

@@ -0,0 +1,70 @@
+require "json"
+require "uri"
+require "httparty"
+
+module InstagramConnect
+  module Auth
+    # Common interface for a Meta login path. Concrete strategies differ only in
+    # the Graph host, the OAuth dialog/exchange endpoints, and the scope set.
+    # Subclasses implement the public methods; the shared token-lifetime helper
+    # and credential accessors live here.
+    class Strategy
+      HTTP_TIMEOUT = 30
+
+      def initialize(config)
+        @config = config
+      end
+
+      # e.g. "https://graph.instagram.com"
+      def graph_host
+        raise NotImplementedError
+      end
+
+      # The scope set requested during OAuth.
+      def scopes
+        raise NotImplementedError
+      end
+
+      # The "log in with…" dialog URL the host redirects the operator to.
+      def authorize_url(redirect_uri:, state:)
+        raise NotImplementedError
+      end
+
+      # Exchange an authorization code for a long-lived token. Returns a hash:
+      #   { access_token:, expires_at:, ig_user_id: (optional), page_id: (optional) }
+      def exchange_code(code:, redirect_uri:)
+        raise NotImplementedError
+      end
+
+      # Refresh a long-lived token. Returns { access_token:, expires_at: }.
+      # Paths whose tokens don't expire return the token unchanged.
+      def refresh_token(access_token:)
+        raise NotImplementedError
+      end
+
+      private
+
+      attr_reader :config
+
+      def app_id
+        value = config.app_id
+        raise ConfigurationError, "app_id is not configured" if value.to_s.empty?
+        value
+      end
+
+      def app_secret
+        value = config.app_secret
+        raise ConfigurationError, "app_secret is not configured" if value.to_s.empty?
+        value
+      end
+
+      def graph_version
+        config.graph_version
+      end
+
+      def expires_at_from(seconds)
+        seconds ? Time.now + seconds.to_i : nil
+      end
+    end
+  end
+end

data/lib/instagram_connect/auth.rb

@@ -0,0 +1,17 @@
+module InstagramConnect
+  # Selects the auth strategy for the configured path. New login paths register
+  # by adding a class to STRATEGIES — the same config-symbol dispatch used
+  # across the house gems.
+  module Auth
+    STRATEGIES = {
+      instagram_login: InstagramLogin,
+      facebook_login: FacebookLogin
+    }.freeze
+
+    def self.for(config)
+      klass = STRATEGIES[config.auth_path]
+      raise ConfigurationError, "unknown auth_path #{config.auth_path.inspect}" unless klass
+      klass.new(config)
+    end
+  end
+end

data/lib/instagram_connect/cli.rb

@@ -0,0 +1,18 @@
+require "thor"
+require_relative "doctor"
+
+module InstagramConnect
+  # Command-line entry point: `bundle exec instagram_connect doctor`.
+  class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "doctor", "Check the instagram_connect configuration"
+    def doctor
+      Doctor.run.each do |check|
+        say(format("%-9s %s", check[:ok] ? "OK" : "MISSING", check[:label]))
+      end
+    end
+  end
+end

data/lib/instagram_connect/client.rb

@@ -0,0 +1,160 @@
+require "httparty"
+
+module InstagramConnect
+  # Thin wrapper over the Meta Graph API, bound to one account's access token.
+  # Every call returns a Result — API-level failures never raise, callers branch
+  # on success?. The Graph host + version come from the configured auth strategy.
+  class Client
+    TIMEOUT = 30
+
+    def initialize(access_token:, config: InstagramConnect.configuration, ig_user_id: nil)
+      @access_token = access_token
+      @config = config
+      @ig_user_id = ig_user_id
+      @strategy = Auth.for(config)
+    end
+
+    # --- Direct messages -------------------------------------------------
+
+    def send_text(recipient_id:, text:, tag: nil)
+      send_message(recipient: { id: recipient_id }, message: { text: text }, tag: tag)
+    end
+
+    def send_media(recipient_id:, url:, type: "image", tag: nil)
+      attachment = { type: type, payload: { url: url } }
+      send_message(recipient: { id: recipient_id }, message: { attachment: attachment }, tag: tag)
+    end
+
+    def send_reaction(recipient_id:, message_id:, reaction: "love")
+      post("/me/messages", {
+        recipient: { id: recipient_id },
+        sender_action: "react",
+        payload: { message_id: message_id, reaction: reaction }
+      })
+    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 } })
+    end
+
+    # --- Comments --------------------------------------------------------
+
+    def reply_comment(comment_id:, text:)
+      post("/#{comment_id}/replies", { message: text })
+    end
+
+    def hide_comment(comment_id:, hidden: true)
+      post("/#{comment_id}", { hide: hidden })
+    end
+
+    def delete_comment(comment_id:)
+      delete("/#{comment_id}")
+    end
+
+    def list_comments(media_id:, limit: 50)
+      get("/#{media_id}/comments", { fields: "id,text,username,timestamp,parent_id", limit: limit })
+    end
+
+    # --- Publishing ------------------------------------------------------
+
+    def create_media_container(ig_user_id: @ig_user_id, **params)
+      post("/#{require_ig_user_id(ig_user_id)}/media", params)
+    end
+
+    def publish_media(creation_id:, ig_user_id: @ig_user_id)
+      post("/#{require_ig_user_id(ig_user_id)}/media_publish", { creation_id: creation_id })
+    end
+
+    def container_status(container_id:)
+      get("/#{container_id}", { fields: "status_code,status" })
+    end
+
+    def publishing_limit(ig_user_id: @ig_user_id)
+      get("/#{require_ig_user_id(ig_user_id)}/content_publishing_limit", { fields: "quota_usage,config" })
+    end
+
+    # --- Reads -----------------------------------------------------------
+
+    def list_media(ig_user_id: @ig_user_id, limit: 25)
+      get("/#{require_ig_user_id(ig_user_id)}/media",
+          { fields: "id,caption,media_type,media_url,permalink,timestamp", limit: limit })
+    end
+
+    def media_insights(media_id:, metrics: %w[reach likes comments])
+      get("/#{media_id}/insights", { metric: Array(metrics).join(",") })
+    end
+
+    def profile(igsid:, fields: %w[name username profile_pic])
+      get("/#{igsid}", { fields: Array(fields).join(",") })
+    end
+
+    # FB-Login only: the Pages this user administers, with their linked IG
+    # business account — used to resolve the account identity after OAuth.
+    def list_pages
+      get("/me/accounts", { fields: "id,name,access_token,instagram_business_account" })
+    end
+
+    def fetch_media_binary(url:)
+      response = HTTParty.get(url, headers: bearer, timeout: TIMEOUT, follow_redirects: true)
+      unless response.success?
+        return Result.error("media fetch failed: HTTP #{response.code}", error_code: response.code)
+      end
+      body = response.body.to_s
+      Result.ok(data: { body: body, mime: response.headers["content-type"], size: body.bytesize })
+    end
+
+    private
+
+    attr_reader :access_token, :config, :strategy
+
+    def send_message(recipient:, message:, tag: nil)
+      body = { recipient: recipient, message: message }
+      if tag
+        body[:messaging_type] = "MESSAGE_TAG"
+        body[:tag] = tag
+      end
+      post("/me/messages", body)
+    end
+
+    def require_ig_user_id(value)
+      value || raise(ConfigurationError, "ig_user_id is required for this call")
+    end
+
+    def get(path, query = {})
+      parse(HTTParty.get(url(path), headers: bearer, query: query, timeout: TIMEOUT))
+    end
+
+    def post(path, body = {})
+      parse(HTTParty.post(url(path),
+                          headers: bearer.merge("Content-Type" => "application/json"),
+                          body: body.to_json, timeout: TIMEOUT))
+    end
+
+    def delete(path)
+      parse(HTTParty.delete(url(path), headers: bearer, timeout: TIMEOUT))
+    end
+
+    def url(path)
+      "#{strategy.graph_host}/#{config.graph_version}#{path}"
+    end
+
+    def bearer
+      { "Authorization" => "Bearer #{access_token}" }
+    end
+
+    def parse(response)
+      data = response.parsed_response
+      data = {} unless data.is_a?(Hash)
+      if response.success?
+        Result.ok(id: data["message_id"] || data["id"], data: data)
+      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)
+      end
+    end
+  end
+end

data/lib/instagram_connect/configuration.rb

@@ -0,0 +1,66 @@
+require "logger"
+
+module InstagramConnect
+  # Host-facing configuration, set via InstagramConnect.configure { |c| ... }.
+  #
+  # +auth_path+ selects which Meta login flow + Graph host the gem talks to:
+  #   :instagram_login  -> graph.instagram.com, no Facebook Page required
+  #   :facebook_login   -> graph.facebook.com, requires a linked Facebook Page
+  #
+  # Secrets fall back to ENV so a host can configure entirely through the
+  # environment (e.g. container secrets) without an initializer edit.
+  class Configuration
+    AUTH_PATHS = %i[instagram_login facebook_login].freeze
+
+    attr_accessor :app_id, :app_secret, :verify_token,
+                  :graph_version, :redirect_uri, :encrypt_tokens,
+                  :parent_controller, :authenticate_with, :current_user_id_resolver,
+                  :on_message, :on_comment, :on_postback,
+                  :logger, :default_per_page, :inherit_host_layout,
+                  :media_max_bytes, :allowed_media_types, :after_connect_redirect
+    attr_reader :auth_path
+
+    def initialize
+      @auth_path = (ENV["INSTAGRAM_CONNECT_AUTH_PATH"] || "instagram_login").to_sym
+      @app_id = ENV["INSTAGRAM_CONNECT_APP_ID"] || ENV["INSTAGRAM_APP_ID"]
+      @app_secret = ENV["INSTAGRAM_CONNECT_APP_SECRET"] || ENV["INSTAGRAM_APP_SECRET"]
+      @verify_token = ENV["INSTAGRAM_CONNECT_VERIFY_TOKEN"] || ENV["INSTAGRAM_VERIFY_TOKEN"]
+      @graph_version = ENV.fetch("INSTAGRAM_CONNECT_GRAPH_VERSION", "v21.0")
+      @redirect_uri = ENV["INSTAGRAM_CONNECT_REDIRECT_URI"]
+      @encrypt_tokens = true
+      @parent_controller = "::ApplicationController"
+      @authenticate_with = nil
+      @current_user_id_resolver = -> { respond_to?(:current_user) && current_user ? current_user.id : nil }
+      @on_message = nil
+      @on_comment = nil
+      @on_postback = nil
+      @logger = Logger.new($stdout)
+      @default_per_page = 25
+      @inherit_host_layout = true
+      # Where the OAuth callback redirects after connecting an account.
+      @after_connect_redirect = "/"
+      @media_max_bytes = 25 * 1024 * 1024
+      @allowed_media_types = %w[
+        image/jpeg image/png image/gif image/webp
+        video/mp4 audio/mpeg audio/aac application/pdf
+      ].freeze
+    end
+
+    # Coerce to a symbol so hosts may pass a string ("facebook_login") from a
+    # config hash or ENV.
+    def auth_path=(value)
+      @auth_path = value&.to_sym
+    end
+
+    # Called by .configure at boot. Validates only structural config (a known
+    # auth_path) so an unconfigured host can still boot; secret presence is
+    # enforced lazily at the point of use (Client / OAuth).
+    def validate!
+      unless AUTH_PATHS.include?(auth_path)
+        raise ConfigurationError,
+          "auth_path must be one of #{AUTH_PATHS.join(', ')} (got #{auth_path.inspect})"
+      end
+      true
+    end
+  end
+end

data/lib/instagram_connect/connect.rb

@@ -0,0 +1,45 @@
+module InstagramConnect
+  # Turns an OAuth authorization code into a persisted Account. Extracted from
+  # the callback controller so the flow is unit-testable without the HTTP layer.
+  class Connect
+    def self.call(code:, redirect_uri:, config: InstagramConnect.configuration, connected_by_id: nil)
+      new(config).call(code: code, redirect_uri: redirect_uri, connected_by_id: connected_by_id)
+    end
+
+    def initialize(config)
+      @config = config
+      @strategy = Auth.for(config)
+    end
+
+    def call(code:, redirect_uri:, connected_by_id: nil)
+      data = @strategy.exchange_code(code: code, redirect_uri: redirect_uri)
+      identity = resolve_identity(data)
+
+      account = Account.find_or_initialize_by(ig_user_id: identity[:ig_user_id])
+      account.assign_attributes(
+        auth_path: @config.auth_path.to_s,
+        access_token: data[:access_token],
+        token_expires_at: data[:expires_at],
+        page_id: identity[:page_id],
+        active: true
+      )
+      account.connected_by_id = connected_by_id unless connected_by_id.nil?
+      account.save!
+      account
+    end
+
+    private
+
+    # IG-Login returns the IG user id directly. FB-Login does not, so we look up
+    # the Page the operator administers and read its linked IG business account.
+    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
+
+      { ig_user_id: page.dig("instagram_business_account", "id"), page_id: page["id"] }
+    end
+  end
+end

data/lib/instagram_connect/doctor.rb

@@ -0,0 +1,22 @@
+module InstagramConnect
+  # Preflight configuration checks, surfaced by the `instagram_connect doctor`
+  # CLI. Returns a list of { label:, ok: } so the CLI (or a host) can render it.
+  class Doctor
+    def self.run(config: InstagramConnect.configuration)
+      [
+        check("auth_path is valid", Configuration::AUTH_PATHS.include?(config.auth_path)),
+        check("app_id is set", present?(config.app_id)),
+        check("app_secret is set", present?(config.app_secret)),
+        check("verify_token is set", present?(config.verify_token))
+      ]
+    end
+
+    def self.check(label, ok)
+      { label: label, ok: ok }
+    end
+
+    def self.present?(value)
+      !value.to_s.empty?
+    end
+  end
+end

data/lib/instagram_connect/engine.rb

@@ -0,0 +1,28 @@
+require "rails/engine"
+
+module InstagramConnect
+  # Mountable, namespace-isolated engine. Unlike whatsapp_notifier, the module
+  # name "InstagramConnect" is the Zeitwerk default camelization of
+  # "instagram_connect", so no inflector override is needed.
+  class Engine < ::Rails::Engine
+    isolate_namespace InstagramConnect
+
+    config.instagram_connect = {}
+
+    # Keep tokens and secrets out of logs.
+    initializer "instagram_connect.filter_sensitive_params" do |app|
+      app.config.filter_parameters += %i[access_token app_secret verify_token hub_verify_token]
+    end
+
+    # Apply any host-provided config.instagram_connect = { ... } hash onto the
+    # gem Configuration via setters (in addition to the initializer DSL).
+    initializer "instagram_connect.configure" do |app|
+      InstagramConnect.configure do |config|
+        app.config.instagram_connect.each do |key, value|
+          setter = "#{key}="
+          config.public_send(setter, value) if config.respond_to?(setter)
+        end
+      end
+    end
+  end
+end

data/lib/instagram_connect/errors.rb

@@ -0,0 +1,25 @@
+module InstagramConnect
+  # Base class for every error raised by the gem.
+  class Error < StandardError; end
+
+  # Raised when the gem is misconfigured — an unknown auth_path, or a required
+  # secret (app_id / app_secret / verify_token) missing at the point of use.
+  class ConfigurationError < Error; end
+
+  # Raised when the Meta Graph API returns a non-success response. Carries the
+  # HTTP status, Meta's application-level error code, and any retry hint so
+  # callers (and the Result object) can react without re-parsing the body.
+  class ApiError < Error
+    attr_reader :status, :error_code, :retry_after
+
+    def initialize(message, status: nil, error_code: nil, retry_after: nil)
+      super(message)
+      @status = status
+      @error_code = error_code
+      @retry_after = retry_after
+    end
+  end
+
+  # Raised when an inbound webhook fails HMAC signature verification.
+  class SignatureError < Error; end
+end