qube_rails 0.2.0

data/lib/qube_rails.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "erb"
+require "qube_rails/version"
+require "qube_rails/backend"
+require "qube_rails/configuration"
+require "qube_rails/cache_dedupe"
+require "qube_rails/database_dedupe"
+require "qube_rails/json_coder"
+require "qube_rails/operation"
+require "qube_rails/request"
+require "qube_rails/sync_status"
+require "qube_rails/connection_events"
+require "qube_rails/question_view"
+require "qube_rails/run_status_view"
+require "qube_rails/view_helpers"
+require "qube_rails/storyboard"
+
+# QuBe Sync's Rails engine: the code that's the same in every Rails app's integration. Your app
+# keeps its own: config/initializers/qube_rails.rb (QubeRails.configure), an operation class per
+# way it starts a workflow (QubeRails::Operation), its class for a connection's events
+# (QubeRails::ConnectionEvents), and `mount QubeRails::Engine => "/"` in config/routes.rb. The
+# engine's own tables (qube_connections, qube_runs, qube_quickbooks_records) keep every
+# connection, every run and every QuickBooks id, so your tables need no QuBe columns.
+module QubeRails
+  # A run whose operation none of config.operations has any more (taken out after it started).
+  class UnknownOperation < StandardError; end
+
+  # A connection's event came before the row's qube_id was saved (create_connection hadn't
+  # returned yet, or its update hadn't committed: a simulated connection sends
+  # connection.connected at once). The job raises it so the queue retries once it's there.
+  class NotReady < StandardError; end
+
+  # Operation.start was given a connection QuBe Sync hasn't made yet (no qube_id): the customer
+  # hasn't finished onboarding, or QuBe Sync didn't answer it.
+  class NotConnected < ArgumentError; end
+
+  # An operation's input has no value for a reference QuickBooks requires (an invoice's
+  # customer_ref): the record has no QuickBooks link on the run's connection and no name to look
+  # it up by. The kit's mapped operations raise it from input, so the start fails, before anything
+  # is sent, saying which reference and which record.
+  class MissingReference < ArgumentError; end
+
+  # QuBe Sync refused a start (422 realtime_required): workflows run on realtime connections, and
+  # this one is standard. Its message says how to upgrade it.
+  class RealtimeRequired < StandardError; end
+
+  # Seconds after an event before a record's pages are told to refresh once more.
+  REFRESH_AGAIN = 5
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    # In config/initializers/qube_rails.rb:
+    #   QubeRails.configure do |config|
+    #     config.operations = { "create_invoice" => "QuickbooksDesktop::CreateInvoice" }
+    #     config.connection_events = "QuickbooksDesktop::ConnectionEvents"
+    #     ...
+    #   end
+    def configure
+      yield config
+      @client = nil
+      config
+    end
+
+    # QuBe Sync's API, through the qube_sync gem (QubeSync::Client): create_connection,
+    # start_run, answer, search, get_run, cancel_run, queue and the rest. A non-2xx answer raises
+    # QubeSync::APIError (status, code, message, body).
+    def client
+      @client ||= Backend.client(api_key: config.api_key, base_url: config.base_url,
+                                 on_retry: method(:log_retry))
+    end
+
+    # A call QuBe Sync didn't answer, sent again (safe calls only, within 60 seconds).
+    def log_retry(info)
+      why = info[:status] || (info[:error] && info[:error].class)
+      logger.warn("QuBe Sync: retrying #{info[:method]} #{info[:url]} (#{why}) " \
+                  "in #{info[:delay].to_f.round(1)} s")
+    end
+
+    # Runs one verified delivery. kind is "run" (QUBE_WEBHOOK_URL/runs/<id>): the run's
+    # operation finds its record and handles the event (QubeRails::Operation#handle); or
+    # "connection" (QUBE_WEBHOOK_URL/connections/<id>): your config.connection_events class
+    # handles it for that connection; or "request" (QUBE_WEBHOOK_URL/requests/<id>): the request's
+    # class handles it (QubeRails::Request#handle). QubeRails::WebhookJob calls it; so does your own queue's
+    # worker when config.enqueue hands deliveries elsewhere.
+    #
+    # body is the delivery's raw body, which the webhook endpoint verified: parsed into its typed
+    # event here, and not verified again, since a job can run after its timestamp's 5 minutes are
+    # up.
+    def run(kind, id, body)
+      event = Backend.parse(body)
+      case kind.to_s
+      when "run" then run_event(id, event)
+      when "connection" then connection_event(id, event)
+      when "request" then request_event(id, event)
+      else raise ArgumentError, "QuBe Sync: a delivery is for a run, a connection or a request, not #{kind.inspect}"
+      end
+    end
+
+    # Tells the pages showing record's runs to refresh: the engine's partials subscribe with
+    # turbo_stream_from(record, :qube_rails). Only in an app with turbo-rails 2 (Turbo 8 page
+    # refreshes) and Action Cable; otherwise nothing. Once now, and once more REFRESH_AGAIN
+    # later (QubeRails::RefreshJob), for a page that was still loading the first time. A
+    # broadcast that fails is logged: the event is applied either way, and a reload shows it.
+    def broadcast_refresh(record)
+      return unless refresh_broadcasts?
+
+      broadcast_refresh_now(record)
+      QubeRails::RefreshJob.set(wait: REFRESH_AGAIN).perform_later(record)
+    rescue StandardError => e
+      logger.warn("QuBe Sync: couldn't tell the page for #{record.class.name} #{record.id} to refresh again " \
+                  "(#{e.class})")
+    end
+
+    def broadcast_refresh_now(record)
+      return unless refresh_broadcasts?
+
+      Turbo::StreamsChannel.broadcast_refresh_to(record, :qube_rails)
+    rescue StandardError => e
+      logger.warn("QuBe Sync: couldn't tell the page for #{record.class.name} #{record.id} to refresh " \
+                  "(#{e.class})")
+    end
+
+    def refresh_broadcasts?
+      defined?(Turbo::StreamsChannel) && Turbo::StreamsChannel.respond_to?(:broadcast_refresh_to)
+    end
+
+    def logger
+      Rails.logger
+    end
+
+    # What the screens say to a person, from I18n under qube_rails.* (config/locales/en.yml has
+    # every key): an app overrides or translates a key in its own locale files. A locale that
+    # lacks a key falls back to the engine's English.
+    def t(key, **options)
+      I18n.t(key, **options, scope: :qube_rails, raise: true)
+    rescue I18n::MissingTranslationData
+      I18n.t(key, **options, scope: :qube_rails, locale: :en)
+    end
+
+    # A run, connection or record that isn't there is dropped with a warning, not raised: the
+    # endpoint answered 404 unless the row existed, and the app saves a record before its run's
+    # row, so by the time a job runs, a missing one was deleted, and retrying would never
+    # succeed. An operation taken out of config.operations raises (UnknownOperation): putting it
+    # back and retrying does.
+    def run_event(id, event)
+      run = Run.find_by(id: id)
+      return dropped("run #{id} isn't there", event) unless run
+
+      operation = config.operation_class(run.operation)
+      raise UnknownOperation, "QuBe Sync: no operation has the slug #{run.operation.inspect}" unless operation
+
+      record = find_run_record(operation, run)
+      return dropped("run #{run.id}'s #{run.record_type} #{run.record_id} isn't there", event) unless record
+
+      operation.new(record, run).handle(event)
+    end
+
+    def request_event(id, event)
+      row = QueuedRequest.find_by(id: id)
+      return dropped("request #{id} isn't there", event) unless row
+
+      request_class = config.operation_class(row.operation)
+      raise UnknownOperation, "QuBe Sync: no operation has the slug #{row.operation.inspect}" unless request_class
+
+      record = find_run_record(request_class, row)
+      return dropped("request #{row.id}'s #{row.record_type} #{row.record_id} isn't there", event) unless record
+
+      request_class.new(record, row).handle(event)
+    end
+
+    def connection_event(id, event)
+      connection = Connection.find_by(id: id)
+      return dropped("connection #{id} isn't there", event) unless connection
+
+      config.connection_events_class.new(connection).handle(event)
+    end
+
+    def find_run_record(operation, run)
+      operation.record_for(run)
+    rescue ActiveRecord::RecordNotFound # a find_record written with find
+      nil
+    end
+
+    def dropped(why, event)
+      logger.warn("QuBe Sync: dropped #{event.event || event.type}: #{why} (deleted since, so it can't be applied)")
+      nil
+    end
+
+    # Forgets the settings and the client: for tests.
+    def reset!
+      @config = nil
+      @client = nil
+    end
+  end
+end
+
+require "qube_rails/engine" if defined?(Rails::Engine)

metadata

@@ -0,0 +1,180 @@
+--- !ruby/object:Gem::Specification
+name: qube_rails
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Garrett Lancaster
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: qube_sync
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: 'The code every Rails app''s QuBe Sync integration shares: the webhook
+  endpoint and its job, onboarding, the question routes and partial, and the Operation
+  and ConnectionEvents bases. Your app keeps its own operations, its connection class
+  and one initializer.'
+email:
+- support@qubesync.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- app/assets/javascripts/qube_rails/question.js
+- app/assets/stylesheets/qube_rails.css
+- app/controllers/concerns/qube_rails/run_authorization.rb
+- app/controllers/qube_rails/connections_controller.rb
+- app/controllers/qube_rails/questions_controller.rb
+- app/controllers/qube_rails/runs_controller.rb
+- app/controllers/qube_rails/storyboard_controller.rb
+- app/controllers/qube_rails/webhooks_controller.rb
+- app/jobs/qube_rails/prune_runs_job.rb
+- app/jobs/qube_rails/refresh_job.rb
+- app/jobs/qube_rails/webhook_job.rb
+- app/models/qube_rails/application_record.rb
+- app/models/qube_rails/connection.rb
+- app/models/qube_rails/notification.rb
+- app/models/qube_rails/queued_request.rb
+- app/models/qube_rails/quickbooks_record.rb
+- app/models/qube_rails/request_delivery.rb
+- app/models/qube_rails/run.rb
+- app/models/qube_rails/sync_mark.rb
+- app/views/qube_rails/_error.html.erb
+- app/views/qube_rails/_question.html.erb
+- app/views/qube_rails/_run_status.html.erb
+- app/views/qube_rails/question/_choice.html.erb
+- app/views/qube_rails/question/_details.html.erb
+- app/views/qube_rails/question/_field.html.erb
+- app/views/qube_rails/question/_footer.html.erb
+- app/views/qube_rails/question/_message.html.erb
+- app/views/qube_rails/question/_pick.html.erb
+- app/views/qube_rails/question/_picks.html.erb
+- app/views/qube_rails/question/_question.html.erb
+- app/views/qube_rails/question/fields/_boolean.html.erb
+- app/views/qube_rails/question/fields/_number.html.erb
+- app/views/qube_rails/question/fields/_rows.html.erb
+- app/views/qube_rails/question/fields/_search.html.erb
+- app/views/qube_rails/question/fields/_select.html.erb
+- app/views/qube_rails/question/fields/_text.html.erb
+- app/views/qube_rails/question/rows/_cell.html.erb
+- app/views/qube_rails/question/rows/_row.html.erb
+- app/views/qube_rails/question/rows/_segmented.html.erb
+- app/views/qube_rails/run_status/_detail.html.erb
+- app/views/qube_rails/run_status/_redeliver.html.erb
+- app/views/qube_rails/run_status/_retry.html.erb
+- app/views/qube_rails/run_status/_stall.html.erb
+- app/views/qube_rails/run_status/_status.html.erb
+- app/views/qube_rails/run_status/_summary.html.erb
+- app/views/qube_rails/storyboard/show.html.erb
+- config/locales/en.yml
+- config/routes.rb
+- db/migrate/20261025000000_create_qube_tables.rb
+- db/migrate/20261026230000_add_qube_sync_status_indexes.rb
+- db/migrate/20261027000000_create_qube_sync_marks.rb
+- db/migrate/20261028000000_create_qube_requests.rb
+- lib/generators/qube_rails/install_generator.rb
+- lib/generators/qube_rails/templates/connection_events.rb.tt
+- lib/generators/qube_rails/templates/initializer.rb.tt
+- lib/generators/qube_rails/workflows_generator.rb
+- lib/qube_rails.rb
+- lib/qube_rails/backend.rb
+- lib/qube_rails/cache_dedupe.rb
+- lib/qube_rails/configuration.rb
+- lib/qube_rails/connection_events.rb
+- lib/qube_rails/database_dedupe.rb
+- lib/qube_rails/engine.rb
+- lib/qube_rails/json_coder.rb
+- lib/qube_rails/operation.rb
+- lib/qube_rails/question_view.rb
+- lib/qube_rails/request.rb
+- lib/qube_rails/rows_view.rb
+- lib/qube_rails/run_status_view.rb
+- lib/qube_rails/storyboard.rb
+- lib/qube_rails/storyboard/ask_about_add.json
+- lib/qube_rails/storyboard/choose.json
+- lib/qube_rails/storyboard/enum_select.json
+- lib/qube_rails/storyboard/missing_record.json
+- lib/qube_rails/storyboard/name_clash.json
+- lib/qube_rails/storyboard/near_match.json
+- lib/qube_rails/storyboard/number_boolean.json
+- lib/qube_rails/storyboard/record_search.json
+- lib/qube_rails/storyboard/refusal.json
+- lib/qube_rails/storyboard/rows.json
+- lib/qube_rails/sync_status.rb
+- lib/qube_rails/version.rb
+- lib/qube_rails/view_helpers.rb
+homepage: https://qubesync.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://qubesync.com
+  documentation_uri: https://docs.qubesync.com
+  source_code_uri: https://github.com/qubeintegrations/qube_rails
+  changelog_uri: https://github.com/qubeintegrations/qube_rails/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: 'QuBe Sync''s Rails engine: the webhook endpoint, onboarding and question
+  routes for QuickBooks Desktop'
+test_files: []