instagram_connect 0.2.1 → 0.3.1

data/lib/instagram_connect/result.rb

@@ -3,15 +3,17 @@ module InstagramConnect
   # 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
+    attr_reader :success, :id, :error_code, :error_message, :retry_after, :data, :usage
 
-    def initialize(success:, id: nil, error_code: nil, error_message: nil, retry_after: nil, data: {})
+    def initialize(success:, id: nil, error_code: nil, error_message: nil, retry_after: nil,
+                   data: {}, usage: nil)
       @success = success
       @id = id
       @error_code = error_code
       @error_message = error_message
       @retry_after = retry_after
       @data = data || {}
+      @usage = usage
     end
 
     def success?
@@ -22,13 +24,31 @@ module InstagramConnect
       !success?
     end
 
+    # Meta's cursor for the next page, or nil when this is the last one. Reading
+    # `paging.next` rather than incrementing an offset is the only correct way
+    # through a Graph collection — results shift under you between calls.
+    def next_cursor
+      data.dig("paging", "cursors", "after").presence if more?
+    end
+
+    def more?
+      data.is_a?(Hash) && data.dig("paging", "next").present?
+    end
+
+    # The rows of a collection response, or [] for a single-object one.
+    def records
+      list = data["data"]
+      list.is_a?(Array) ? list : []
+    end
+
     # Convenience builders so call sites read cleanly.
-    def self.ok(id: nil, data: {})
-      new(success: true, id: id, data: data)
+    def self.ok(id: nil, data: {}, usage: nil)
+      new(success: true, id: id, data: data, usage: usage)
     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)
+    def self.error(message, error_code: nil, retry_after: nil, data: {}, usage: nil)
+      new(success: false, error_message: message, error_code: error_code,
+          retry_after: retry_after, data: data, usage: usage)
     end
   end
 end

data/lib/instagram_connect/text_splitter.rb

@@ -0,0 +1,51 @@
+module InstagramConnect
+  # Splits a reply that exceeds Meta's 1000-byte message ceiling into parts that
+  # fit.
+  #
+  # Splitting rather than truncating is deliberate: a customer reading half an
+  # answer is worse than reading two bubbles, and the operator who wrote it has
+  # no way to know it was cut.
+  module TextSplitter
+    module_function
+
+    # Returns the parts to send, in order. A message already within the limit
+    # comes back as a single-element array, so callers have one code path.
+    def split(text, limit: Media::Limits::TEXT_MAX_BYTES)
+      text = text.to_s
+      return [ text ] if text.bytesize <= limit
+
+      parts = []
+      remaining = text
+
+      while remaining.bytesize > limit
+        chunk = take(remaining, limit)
+        parts << chunk.rstrip
+        remaining = remaining[chunk.length..].to_s.lstrip
+      end
+
+      # Text that divides exactly on a break leaves nothing over; appending an
+      # empty part would send an empty bubble.
+      parts << remaining unless remaining.empty?
+      parts
+    end
+
+    # The longest prefix that fits, broken at whitespace where possible so words
+    # survive. Falls back to a hard character break for input with no
+    # whitespace at all — a long URL, or a script that does not use spaces.
+    def take(text, limit)
+      candidate = +""
+      last_break = nil
+
+      text.each_char do |char|
+        break if candidate.bytesize + char.bytesize > limit
+
+        candidate << char
+        last_break = candidate.length if char.match?(/\s/)
+      end
+
+      return candidate if last_break.nil?
+
+      candidate[0, last_break]
+    end
+  end
+end

data/lib/instagram_connect/usage.rb

@@ -0,0 +1,68 @@
+require "json"
+
+module InstagramConnect
+  # Meta's own account of how much of the rate budget a call just consumed,
+  # parsed from the response headers.
+  #
+  # This is worth having because the documented formula — 4800 calls per 24
+  # hours multiplied by the account's impressions — depends on a number the
+  # messaging API never returns. Any budget computed locally is a guess. These
+  # headers are Meta telling you the answer directly, so they are treated as
+  # ground truth and the arithmetic only as a fallback.
+  class Usage
+    HEADERS = %w[x-business-use-case-usage x-app-usage].freeze
+
+    # Back off well before the wall: at 100% Meta stops answering, and the
+    # penalty is measured in hours.
+    WARN_AT = 80
+    CRITICAL_AT = 95
+
+    attr_reader :call_count, :total_cputime, :total_time, :estimated_time_to_regain_access
+
+    def initialize(call_count: 0, total_cputime: 0, total_time: 0, estimated_time_to_regain_access: nil)
+      @call_count = call_count.to_i
+      @total_cputime = total_cputime.to_i
+      @total_time = total_time.to_i
+      @estimated_time_to_regain_access = estimated_time_to_regain_access
+    end
+
+    # Returns nil when Meta sent no usage headers, which is normal for some
+    # endpoints — absence is not zero usage and must not be read as headroom.
+    def self.from_headers(headers)
+      raw = HEADERS.filter_map { |name| headers&.[](name) }.first
+      return nil if raw.blank?
+
+      payload = JSON.parse(raw)
+      # The business header is keyed by object id and holds an array; the app
+      # header is a flat hash.
+      metrics = payload.is_a?(Hash) && payload.values.first.is_a?(Array) ? payload.values.first.first : payload
+      return nil unless metrics.is_a?(Hash)
+
+      new(
+        call_count: metrics["call_count"],
+        total_cputime: metrics["total_cputime"],
+        total_time: metrics["total_time"],
+        estimated_time_to_regain_access: metrics["estimated_time_to_regain_access"]
+      )
+    rescue JSON::ParserError
+      nil
+    end
+
+    # The worst of the three, since exhausting any one of them throttles the app.
+    def percentage
+      [ call_count, total_cputime, total_time ].max
+    end
+
+    def warning?
+      percentage >= WARN_AT
+    end
+
+    def critical?
+      percentage >= CRITICAL_AT
+    end
+
+    def retry_after
+      estimated_time_to_regain_access.to_i * 60 if estimated_time_to_regain_access.to_i.positive?
+    end
+  end
+end

data/lib/instagram_connect/version.rb

@@ -1,3 +1,3 @@
 module InstagramConnect
-  VERSION = "0.2.1"
+  VERSION = "0.3.1"
 end

data/lib/instagram_connect.rb

@@ -1,6 +1,7 @@
 require "logger"
 require_relative "instagram_connect/version"
 require_relative "instagram_connect/errors"
+require_relative "instagram_connect/usage"
 require_relative "instagram_connect/result"
 require_relative "instagram_connect/configuration"
 require_relative "instagram_connect/auth/strategy"
@@ -10,8 +11,12 @@ 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/media/limits"
+require_relative "instagram_connect/media/attaching"
+require_relative "instagram_connect/text_splitter"
 require_relative "instagram_connect/messaging_window"
 require_relative "instagram_connect/ingest"
+require_relative "instagram_connect/rate_limiter"
 require_relative "instagram_connect/doctor"
 
 # InstagramConnect connects a Rails app to Instagram over the official Meta
@@ -25,6 +30,24 @@ require_relative "instagram_connect/doctor"
 #     c.verify_token = Rails.application.credentials.dig(:instagram_connect, :verify_token)
 #   end
 module InstagramConnect
+  # Every table the gem's migrations own, in dependency order (parents first).
+  # Hosts use it to audit what the engine added to their schema; the suite uses
+  # it to assert the migrations actually built what the models expect.
+  TABLES = %w[
+    instagram_connect_accounts
+    instagram_connect_conversations
+    instagram_connect_messages
+    instagram_connect_inbound_messages
+    instagram_connect_comments
+    instagram_connect_webhook_events
+    instagram_connect_message_reactions
+    instagram_connect_message_attachments
+    instagram_connect_media
+    instagram_connect_mentions
+    instagram_connect_insight_snapshots
+    instagram_connect_api_budgets
+  ].freeze
+
   class << self
     def configuration
       @configuration ||= Configuration.new

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: instagram_connect
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.1
 platform: ruby
 authors:
 - Kshitiz Sinha
@@ -51,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: marcel
+  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
@@ -67,7 +81,6 @@ files:
 - CHANGELOG.md
 - Gemfile
 - LICENSE.txt
-- MIT-LICENSE
 - README.md
 - Rakefile
 - app/assets/stylesheets/instagram_connect/application.css
@@ -79,16 +92,27 @@ files:
 - app/controllers/instagram_connect/posts_controller.rb
 - app/controllers/instagram_connect/webhooks_controller.rb
 - app/helpers/instagram_connect/application_helper.rb
+- app/jobs/instagram_connect/account_readiness_job.rb
 - app/jobs/instagram_connect/application_job.rb
+- app/jobs/instagram_connect/fetch_media_job.rb
 - app/jobs/instagram_connect/ingest_job.rb
+- app/jobs/instagram_connect/profile_sync_job.rb
 - app/jobs/instagram_connect/refresh_tokens_job.rb
+- app/jobs/instagram_connect/replay_events_job.rb
 - app/jobs/instagram_connect/send_message_job.rb
 - app/models/instagram_connect/account.rb
+- app/models/instagram_connect/api_budget.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/insight_snapshot.rb
+- app/models/instagram_connect/media_item.rb
+- app/models/instagram_connect/mention.rb
 - app/models/instagram_connect/message.rb
+- app/models/instagram_connect/message_attachment.rb
+- app/models/instagram_connect/message_reaction.rb
+- app/models/instagram_connect/webhook_event.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
@@ -106,6 +130,19 @@ files:
 - db/migrate/20260715072550_create_instagram_connect_messages.rb
 - db/migrate/20260715072551_create_instagram_connect_inbound_messages.rb
 - db/migrate/20260715072552_create_instagram_connect_comments.rb
+- db/migrate/20260725194732_create_instagram_connect_webhook_events.rb
+- db/migrate/20260725200216_add_messaging_event_fields.rb
+- db/migrate/20260725200250_create_instagram_connect_message_reactions.rb
+- db/migrate/20260725201320_create_instagram_connect_message_attachments.rb
+- db/migrate/20260725202616_add_outbound_send_fields.rb
+- db/migrate/20260725203213_create_instagram_connect_media.rb
+- db/migrate/20260725203214_create_instagram_connect_mentions.rb
+- db/migrate/20260725203215_create_instagram_connect_insight_snapshots.rb
+- db/migrate/20260725203306_add_comment_moderation_fields.rb
+- db/migrate/20260725204022_add_per_account_token_fields.rb
+- db/migrate/20260725204815_create_instagram_connect_api_budgets.rb
+- db/migrate/20260725205417_add_conversation_profile_fields.rb
+- docs/CONFIGURATION.md
 - docs/app_review_guide.md
 - docs/auth_paths.md
 - docs/roadmap.md
@@ -126,10 +163,31 @@ files:
 - lib/instagram_connect/engine.rb
 - lib/instagram_connect/errors.rb
 - lib/instagram_connect/ingest.rb
+- lib/instagram_connect/ingest/dispatcher.rb
+- lib/instagram_connect/ingest/envelope.rb
+- lib/instagram_connect/ingest/handlers/base.rb
+- lib/instagram_connect/ingest/handlers/comments.rb
+- lib/instagram_connect/ingest/handlers/mentions.rb
+- lib/instagram_connect/ingest/handlers/message_reactions.rb
+- lib/instagram_connect/ingest/handlers/messages.rb
+- lib/instagram_connect/ingest/handlers/messaging_handover.rb
+- lib/instagram_connect/ingest/handlers/messaging_optins.rb
+- lib/instagram_connect/ingest/handlers/messaging_postbacks.rb
+- lib/instagram_connect/ingest/handlers/messaging_referral.rb
+- lib/instagram_connect/ingest/handlers/messaging_seen.rb
+- lib/instagram_connect/ingest/handlers/story_insights.rb
+- lib/instagram_connect/ingest/handlers/unknown.rb
+- lib/instagram_connect/ingest/registry.rb
+- lib/instagram_connect/ingest/summary.rb
+- lib/instagram_connect/media/attaching.rb
+- lib/instagram_connect/media/limits.rb
 - lib/instagram_connect/messaging_window.rb
 - lib/instagram_connect/railtie.rb
+- lib/instagram_connect/rate_limiter.rb
 - lib/instagram_connect/result.rb
 - lib/instagram_connect/signature_verifier.rb
+- lib/instagram_connect/text_splitter.rb
+- lib/instagram_connect/usage.rb
 - lib/instagram_connect/version.rb
 homepage: https://github.com/kshtzkr/instagram_connect
 licenses:

data/MIT-LICENSE

@@ -1,20 +0,0 @@
-Copyright (c) 2026 Kshitiz Sinha
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.