instagram_connect 0.1.0

data/lib/instagram_connect/ingest.rb

@@ -0,0 +1,112 @@
+module InstagramConnect
+  # Parses a verified Meta webhook payload and persists it into the engine's
+  # chat models, deduping on Meta's message id. After persistence it fires the
+  # configured host handlers (on_message / on_comment / on_postback) so the host
+  # can layer extras (notifications, AI replies) on top.
+  #
+  # Returns a summary hash of what was processed.
+  class Ingest
+    def self.call(payload:, config: InstagramConnect.configuration)
+      new(config).call(payload)
+    end
+
+    def initialize(config)
+      @config = config
+    end
+
+    def call(payload)
+      summary = { messages: 0, comments: 0, postbacks: 0, skipped: 0 }
+      Array(payload && payload["entry"]).each do |entry|
+        account = account_for(entry)
+        if account.nil?
+          summary[:skipped] += 1
+          next
+        end
+        Array(entry["messaging"]).each { |event| ingest_messaging(account, event, summary) }
+        Array(entry["changes"]).each { |change| ingest_change(account, change, summary) }
+      end
+      summary
+    end
+
+    private
+
+    attr_reader :config
+
+    def account_for(entry)
+      id = entry["id"].to_s
+      Account.find_by(ig_user_id: id) || Account.find_by(page_id: id)
+    end
+
+    def ingest_messaging(account, event, summary)
+      if event["message"]
+        ingest_message(account, event, summary)
+      elsif event["postback"]
+        invoke(config.on_postback, build_postback(account, event))
+        summary[:postbacks] += 1
+      else
+        summary[:skipped] += 1
+      end
+    end
+
+    def ingest_message(account, event, summary)
+      msg = event["message"]
+      mid = msg["mid"].to_s
+      if mid.empty? || !InboundMessage.claim(ig_message_id: mid, account_id: account.id)
+        summary[:skipped] += 1
+        return
+      end
+
+      echo = msg["is_echo"] ? true : false
+      igsid = (echo ? event.dig("recipient", "id") : event.dig("sender", "id")).to_s
+      conversation = Conversation.locate(account: account, igsid: igsid)
+      message = Message.create!(
+        conversation: conversation,
+        direction: echo ? "outbound" : "inbound",
+        status: echo ? "sent" : "received",
+        source: echo ? "operator_app" : "inbound",
+        kind: "dm",
+        body: msg["text"],
+        ig_message_id: mid,
+        media_status: media?(msg) ? "pending" : "none"
+      )
+      conversation.register_message(message)
+      invoke(config.on_message, message) unless echo
+      summary[:messages] += 1
+    end
+
+    def ingest_change(account, change, summary)
+      unless change["field"] == "comments"
+        summary[:skipped] += 1
+        return
+      end
+      value = change["value"] || {}
+      comment = Comment.record(
+        account: account,
+        comment_id: value["id"].to_s,
+        media_id: value.dig("media", "id"),
+        text: value["text"],
+        from_username: value.dig("from", "username"),
+        parent_id: value["parent_id"]
+      )
+      invoke(config.on_comment, comment)
+      summary[:comments] += 1
+    end
+
+    def media?(msg)
+      Array(msg["attachments"]).any?
+    end
+
+    def build_postback(account, event)
+      {
+        account_id: account.id,
+        sender_id: event.dig("sender", "id"),
+        payload: event.dig("postback", "payload"),
+        title: event.dig("postback", "title")
+      }
+    end
+
+    def invoke(handler, arg)
+      handler.call(arg) if handler.respond_to?(:call)
+    end
+  end
+end

data/lib/instagram_connect/messaging_window.rb

@@ -0,0 +1,42 @@
+module InstagramConnect
+  # Encodes Meta's outbound messaging window. After a user's last inbound
+  # message a business may send standard replies for 24h; the HUMAN_AGENT tag
+  # extends that to 7 days (human replies only). Beyond that, nothing may be
+  # sent until the user messages again.
+  class MessagingWindow
+    STANDARD_SECONDS = 24 * 60 * 60
+    HUMAN_AGENT_SECONDS = 7 * 24 * 60 * 60
+
+    def initialize(last_inbound_at:, now: Time.now)
+      @last_inbound_at = last_inbound_at
+      @now = now
+    end
+
+    def state
+      return :closed if @last_inbound_at.nil?
+
+      elapsed = @now - @last_inbound_at
+      return :standard if elapsed <= STANDARD_SECONDS
+      return :human_agent if elapsed <= HUMAN_AGENT_SECONDS
+
+      :closed
+    end
+
+    def open?
+      state != :closed
+    end
+
+    def standard?
+      state == :standard
+    end
+
+    # The message tag to send with, or :blocked when no send is permitted.
+    def send_tag
+      case state
+      when :standard then nil
+      when :human_agent then "HUMAN_AGENT"
+      else :blocked
+      end
+    end
+  end
+end

data/lib/instagram_connect/railtie.rb

@@ -0,0 +1,19 @@
+require "rails/railtie"
+
+module InstagramConnect
+  # Loaded when Rails is present but the full Engine is not (e.g. a bare Rails
+  # app that only wants the client, not the mounted UI). Mirrors the engine's
+  # configure initializer.
+  class Railtie < ::Rails::Railtie
+    config.instagram_connect = {}
+
+    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/result.rb

@@ -0,0 +1,34 @@
+module InstagramConnect
+  # Value object returned by every Client call. Client methods never raise for
+  # API-level failures — callers branch on +success?+ and read +error_code+ /
+  # +error_message+. Transport/programming errors still raise.
+  class Result
+    attr_reader :success, :id, :error_code, :error_message, :retry_after, :data
+
+    def initialize(success:, id: nil, error_code: nil, error_message: nil, retry_after: nil, data: {})
+      @success = success
+      @id = id
+      @error_code = error_code
+      @error_message = error_message
+      @retry_after = retry_after
+      @data = data || {}
+    end
+
+    def success?
+      success
+    end
+
+    def failure?
+      !success?
+    end
+
+    # Convenience builders so call sites read cleanly.
+    def self.ok(id: nil, data: {})
+      new(success: true, id: id, data: data)
+    end
+
+    def self.error(message, error_code: nil, retry_after: nil, data: {})
+      new(success: false, error_message: message, error_code: error_code, retry_after: retry_after, data: data)
+    end
+  end
+end

data/lib/instagram_connect/signature_verifier.rb

@@ -0,0 +1,23 @@
+require "openssl"
+
+module InstagramConnect
+  # Verifies Meta's `X-Hub-Signature-256` header: HMAC-SHA256 of the raw request
+  # body keyed by the app secret, compared in constant time. This is how the
+  # webhook authenticates that a POST really came from Meta.
+  module SignatureVerifier
+    module_function
+
+    def valid?(raw_body:, signature:, app_secret: InstagramConnect.configuration.app_secret)
+      return false if signature.to_s.empty? || app_secret.to_s.empty?
+
+      expected = "sha256=#{OpenSSL::HMAC.hexdigest('SHA256', app_secret.to_s, raw_body.to_s)}"
+      secure_compare(signature.to_s, expected)
+    end
+
+    def secure_compare(given, expected)
+      return false unless given.bytesize == expected.bytesize
+
+      OpenSSL.fixed_length_secure_compare(given, expected)
+    end
+  end
+end

data/lib/instagram_connect/version.rb

@@ -0,0 +1,3 @@
+module InstagramConnect
+  VERSION = "0.1.0"
+end

data/lib/instagram_connect.rb

@@ -0,0 +1,53 @@
+require "logger"
+require_relative "instagram_connect/version"
+require_relative "instagram_connect/errors"
+require_relative "instagram_connect/result"
+require_relative "instagram_connect/configuration"
+require_relative "instagram_connect/auth/strategy"
+require_relative "instagram_connect/auth/instagram_login"
+require_relative "instagram_connect/auth/facebook_login"
+require_relative "instagram_connect/auth"
+require_relative "instagram_connect/client"
+require_relative "instagram_connect/connect"
+require_relative "instagram_connect/signature_verifier"
+require_relative "instagram_connect/messaging_window"
+require_relative "instagram_connect/ingest"
+require_relative "instagram_connect/doctor"
+
+# InstagramConnect connects a Rails 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.
+#
+#   InstagramConnect.configure do |c|
+#     c.auth_path   = :facebook_login
+#     c.app_id      = Rails.application.credentials.dig(:instagram_connect, :app_id)
+#     c.app_secret  = Rails.application.credentials.dig(:instagram_connect, :app_secret)
+#     c.verify_token = Rails.application.credentials.dig(:instagram_connect, :verify_token)
+#   end
+module InstagramConnect
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    attr_writer :configuration
+
+    def configure
+      yield(configuration)
+      configuration.validate!
+      configuration
+    end
+
+    def reset!
+      @configuration = Configuration.new
+    end
+  end
+end
+
+# simplecov:disable
+if defined?(Rails::Engine)
+  require_relative "instagram_connect/engine"
+elsif defined?(Rails::Railtie)
+  require_relative "instagram_connect/railtie"
+end
+# simplecov:enable

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification
+name: instagram_connect
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kshitiz Sinha
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: 'A mountable Rails engine that connects your app to Instagram: receive
+  and reply to DMs and comments in real time over HMAC-verified webhooks, publish
+  posts, and manage OAuth tokens — using the official Instagram Graph API (Instagram-Login
+  or Facebook-Login), no unofficial automation.'
+email:
+- kshtzkr@gmail.com
+executables:
+- instagram_connect
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".rspec"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/instagram_connect/application_controller.rb
+- app/controllers/instagram_connect/comments_controller.rb
+- app/controllers/instagram_connect/conversations_controller.rb
+- app/controllers/instagram_connect/messages_controller.rb
+- app/controllers/instagram_connect/oauth_controller.rb
+- app/controllers/instagram_connect/posts_controller.rb
+- app/controllers/instagram_connect/webhooks_controller.rb
+- app/jobs/instagram_connect/application_job.rb
+- app/jobs/instagram_connect/ingest_job.rb
+- app/jobs/instagram_connect/refresh_tokens_job.rb
+- app/jobs/instagram_connect/send_message_job.rb
+- app/models/instagram_connect/account.rb
+- app/models/instagram_connect/application_record.rb
+- app/models/instagram_connect/comment.rb
+- app/models/instagram_connect/conversation.rb
+- app/models/instagram_connect/inbound_message.rb
+- app/models/instagram_connect/message.rb
+- app/views/instagram_connect/comments/_comment.html.erb
+- app/views/instagram_connect/comments/index.html.erb
+- app/views/instagram_connect/conversations/_composer.html.erb
+- app/views/instagram_connect/conversations/_conversation.html.erb
+- app/views/instagram_connect/conversations/_message.html.erb
+- app/views/instagram_connect/conversations/index.html.erb
+- app/views/instagram_connect/conversations/show.html.erb
+- app/views/instagram_connect/posts/index.html.erb
+- app/views/instagram_connect/posts/new.html.erb
+- app/views/layouts/instagram_connect/application.html.erb
+- bin/instagram_connect
+- config/routes.rb
+- docs/app_review_guide.md
+- docs/auth_paths.md
+- docs/roadmap.md
+- lib/generators/instagram_connect/controllers_generator.rb
+- lib/generators/instagram_connect/install/install_generator.rb
+- lib/generators/instagram_connect/install/templates/create_instagram_connect_accounts.rb.tt
+- lib/generators/instagram_connect/install/templates/create_instagram_connect_comments.rb.tt
+- lib/generators/instagram_connect/install/templates/create_instagram_connect_conversations.rb.tt
+- lib/generators/instagram_connect/install/templates/create_instagram_connect_inbound_messages.rb.tt
+- lib/generators/instagram_connect/install/templates/create_instagram_connect_messages.rb.tt
+- lib/generators/instagram_connect/install/templates/instagram_connect.rb.tt
+- lib/generators/instagram_connect/views_generator.rb
+- lib/instagram_connect.rb
+- lib/instagram_connect/auth.rb
+- lib/instagram_connect/auth/facebook_login.rb
+- lib/instagram_connect/auth/instagram_login.rb
+- lib/instagram_connect/auth/strategy.rb
+- lib/instagram_connect/cli.rb
+- lib/instagram_connect/client.rb
+- lib/instagram_connect/configuration.rb
+- lib/instagram_connect/connect.rb
+- lib/instagram_connect/doctor.rb
+- lib/instagram_connect/engine.rb
+- lib/instagram_connect/errors.rb
+- lib/instagram_connect/ingest.rb
+- lib/instagram_connect/messaging_window.rb
+- lib/instagram_connect/railtie.rb
+- lib/instagram_connect/result.rb
+- lib/instagram_connect/signature_verifier.rb
+- lib/instagram_connect/version.rb
+homepage: https://github.com/kshtzkr/instagram_connect
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/kshtzkr/instagram_connect
+  source_code_uri: https://github.com/kshtzkr/instagram_connect/tree/main
+  changelog_uri: https://github.com/kshtzkr/instagram_connect/releases
+  bug_tracker_uri: https://github.com/kshtzkr/instagram_connect/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Instagram DMs, comments, and publishing for Rails via the official Meta Graph
+  API.
+test_files: []