qube_rails 0.2.0

data/db/migrate/20261027000000_create_qube_sync_marks.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# When each connection's last completed run of a workflow started: a sync's next since, kept
+# apart from qube_runs so pruning runs never loses it.
+class CreateQubeSyncMarks < ActiveRecord::Migration[5.2]
+  def change
+    create_table :qube_sync_marks do |t|
+      t.bigint :connection_id, null: false
+      t.string :workflow, null: false, limit: 100
+      t.datetime :started_at, null: false
+      t.timestamps
+    end
+    add_index :qube_sync_marks, [:connection_id, :workflow], unique: true,
+              name: "index_qube_sync_marks_on_connection_and_workflow"
+    add_foreign_key :qube_sync_marks, :qube_connections, column: :connection_id, on_delete: :cascade
+  end
+end

data/db/migrate/20261028000000_create_qube_requests.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Plain v2 requests your app queues (QubeRails::Request), and the deliveries each has taken, by
+# page_request_id and state. params and error are JSON kept as text; never a response body.
+class CreateQubeRequests < ActiveRecord::Migration[5.2]
+  def change
+    create_table :qube_requests do |t|
+      t.bigint :connection_id, null: false
+      t.string :operation, null: false, limit: 100
+      t.string :record_type, null: false, limit: 100
+      t.string :record_id, null: false
+      t.string :reference, null: false
+      t.string :qube_id
+      t.string :state, null: false, default: "queued", limit: 50
+      t.text :params
+      t.text :error
+      t.integer :pages_answered, null: false, default: 0
+      t.integer :last_page
+      t.datetime :ended_at
+      t.timestamps null: false
+    end
+    add_index :qube_requests, :reference, unique: true, name: "index_qube_requests_on_reference"
+    add_index :qube_requests, [:connection_id, :record_type, :record_id, :operation, :created_at],
+              name: "index_qube_requests_on_connection_and_record"
+    add_foreign_key :qube_requests, :qube_connections, column: :connection_id
+
+    create_table :qube_request_deliveries do |t|
+      t.bigint :request_id, null: false
+      t.string :dedupe_key, null: false, limit: 200
+      t.integer :page
+      t.string :state, null: false, limit: 50
+      t.datetime :created_at, null: false
+    end
+    add_index :qube_request_deliveries, [:request_id, :dedupe_key], unique: true,
+              name: "index_qube_request_deliveries_on_request_and_key"
+    add_foreign_key :qube_request_deliveries, :qube_requests, column: :request_id, on_delete: :cascade
+  end
+end

data/lib/generators/qube_rails/install_generator.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module QubeRails
+  module Generators
+    # rails g qube_rails:install
+    #
+    # Writes the app's side of a QuBe Sync integration, for an app that doesn't start from the
+    # integration kit: config/initializers/qube_rails.rb (every setting, commented), your class
+    # for a connection's events (app/services/quickbooks_desktop/connection_events.rb), the
+    # engine's migration (qube_connections, qube_runs, qube_notifications and
+    # qube_quickbooks_records, through `qube_rails:install:migrations`), the engine's mount
+    # line in config/routes.rb, and qube_rails_assets in your layout. Your own tables need nothing.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/qube_rails.rb"
+      end
+
+      def create_connection_events
+        template "connection_events.rb.tt", "app/services/quickbooks_desktop/connection_events.rb"
+      end
+
+      def copy_migrations
+        rails_command "qube_rails:install:migrations"
+      end
+
+      def mount_engine
+        route 'mount QubeRails::Engine => "/"'
+      end
+
+      # The question's behaviour script (its search boxes and rows table), in the layout's <head>.
+      def include_assets
+        layout = "app/views/layouts/application.html.erb"
+        path = File.join(destination_root, layout)
+        unless File.exist?(path)
+          return say_status(:skip, "no #{layout}: add <%= qube_rails_assets %> to your layout's <head>", :yellow)
+        end
+        return if File.read(path).include?("qube_rails_assets")
+
+        insert_into_file layout, "    <%= qube_rails_assets %>\n", before: "  </head>"
+      end
+    end
+  end
+end

data/lib/generators/qube_rails/templates/connection_events.rb.tt

@@ -0,0 +1,38 @@
+# What your app does when one of its customers' QuickBooks Desktop connections changes. The
+# qube_rails gem does the rest: it checks each event is this connection's and newer than the
+# last one applied, under the connection row's lock, and updates the row's status
+# ("connected", "setup_cancelled", "stalled") and stall_reason before your handler runs.
+#
+# connection is the QubeRails::Connection (one company file; an account can have several) and
+# owner the account that connected it. Start a run on it with
+# QuickbooksDesktop::<Operation>.start(record, connection).
+module QuickbooksDesktop
+  class ConnectionEvents < QubeRails::ConnectionEvents
+    # QuickBooks is connected: show it, and start syncing.
+    def connected(event)
+      log_event(event)
+    end
+
+    # They chose "Cancel setup" on the setup page: offer to set it up again
+    # (POST /quickbooks/connections/<id>/onboarding).
+    def setup_cancelled(event)
+      log_event(event)
+    end
+
+    # Your requests are waiting and QuickBooks hasn't been reached. Show the customer, and tell
+    # them what connection.stall_reason says:
+    # - "not_checking_in": the Web Connector isn't calling in. Turn on the QuickBooks computer,
+    #   and check the Web Connector runs.
+    # - "quickbooks_unavailable": it is calling in and can't reach QuickBooks. Open QuickBooks
+    #   with the company file.
+    # A stall can send this again with a new reason: show the newest. resumed clears it.
+    def stalled(event)
+      log_event(event)
+    end
+
+    # Clear what stalled showed, whichever its reason.
+    def resumed(event)
+      log_event(event)
+    end
+  end
+end

data/lib/generators/qube_rails/templates/initializer.rb.tt

@@ -0,0 +1,82 @@
+# QuBe Sync (qube_rails): the only place the engine reads your app from. A setting left unset
+# raises QubeRails::NotConfigured, naming this file, the first time it's needed. Fill in
+# current_account before anything else.
+#
+# The engine's routes come from `mount QubeRails::Engine => "/"` in config/routes.rb:
+#   POST /quickbooks/connections                 a new connection for the signed-in account
+#   POST /quickbooks/connections/:id/onboarding  one of its connections, through setup again
+#   POST /webhooks/qube/runs/:id                 QuBe Sync's webhooks (signed, no sign-in)
+#   POST /webhooks/qube/connections/:id
+#   POST /qube/questions/runs/:id                an answer, behind your sign-in and CSRF
+#   GET  /qube/questions/runs/:id/search         a record field's matches
+#   GET  /qube/storyboard                        every screen, sample data (config.storyboard)
+#
+# Its tables (qube_connections, qube_runs, qube_notifications, qube_quickbooks_records) keep
+# every connection, run and QuickBooks id; your own tables need nothing.
+QubeRails.configure do |config|
+  # Each operation by its SLUG, as class names (resolved when used, so code reloading works).
+  # Add one per QubeRails::Operation subclass in app/services/quickbooks_desktop/.
+  config.operations = {
+    # "create_invoice" => "QuickbooksDesktop::CreateInvoice",
+  }
+
+  # Your class for a connection's own events (connected, setup cancelled, stalled, resumed).
+  config.connection_events = "QuickbooksDesktop::ConnectionEvents"
+
+  # The signed-in customer's account, from the controller handling the request (your
+  # current_user and other helpers are on it). It owns the connections it makes, and only its
+  # own can be set up again; nil answers 401.
+  # config.current_account = ->(controller) { controller.current_user.account }
+
+  # Whether the signed-in user may answer or search the question run asks about record. By
+  # default, yes when the signed-in account (current_account) owns the run's connection, and no
+  # (404, logged) otherwise. Set it to check more, such as whether this user may see the record,
+  # or to let staff act across accounts. Only true allows.
+  # config.authorize_question = ->(controller, record, run) {
+  #   run.connection.owner == controller.current_user.account &&
+  #     controller.current_user.can_edit?(record)
+  # }
+
+  # How a verified webhook reaches a worker. The default is ActiveJob (QubeRails::WebhookJob) on
+  # config.queue. For another queue, hand it on and call QubeRails.run from its worker:
+  # config.enqueue = ->(delivery) {
+  #   MyQueue.push(delivery[:kind], delivery[:id], delivery[:body])
+  # }
+  # config.queue = :default
+
+  # Delete ended runs after this long, when QubeRails::PruneRunsJob runs (schedule it). Off
+  # until set.
+  # config.prune_runs_after = 90.days
+
+  # Onboarding makes realtime connections: workflows run only on those (billed as realtime).
+  # config.connection_type = "realtime"
+  # How many times QubeRails::WebhookJob runs a delivery whose work raised, with a growing wait,
+  # before it logs an error and raises to your adapter. With Sidekiq, whose own retries follow,
+  # a smaller number (or 1, to leave retries to Sidekiq) avoids retrying twice over.
+  # config.job_attempts = 10
+
+  # Where notification delivery ids are remembered, so a redelivery runs its handler once. The
+  # default is the engine's qube_notifications table, written in the same transaction as the
+  # handler. Rails.cache instead needs a cache your workers share, and isn't transactional:
+  # config.dedupe = QubeRails::CacheDedupe.new(Rails.cache, expires_in: 1.day)
+
+  # Your CSS framework's classes for the engine's screens, by piece, added beside their qube-
+  # classes (pieces: QubeRails::Configuration::UI_PIECES; see the README's "Styling"):
+  # config.ui_classes = { button: "btn btn-primary", button_secondary: "btn btn-link",
+  #                       input: "form-control", select: "form-select", label: "form-label" }
+
+  # GET /qube/storyboard: every screen with sample data, in your layout. On in development.
+  # config.storyboard = Rails.env.development?
+
+  # The controller onboarding and the questions inherit, so your sign-in and CSRF apply.
+  # config.parent_controller = "ApplicationController"
+
+  # Read from the environment when unset: QUBE_API_KEY, QUBE_URL (https://qubesync.com) and
+  # QUBE_WEBHOOK_SECRET, which `qube env --write .env` writes, and QUBE_WEBHOOK_URL, the base of
+  # each webhook URL (`qube listen --write-env .env` in development; your app's /webhooks/qube in
+  # production). webhook_secret may be a list while a secret rotates. Never logged.
+  # config.api_key = ENV.fetch("QUBE_API_KEY")
+  # config.base_url = "https://qubesync.com"
+  # config.webhook_secret = [ENV.fetch("QUBE_WEBHOOK_SECRET"), ENV.fetch("QUBE_WEBHOOK_SECRET_OLD")]
+  # config.webhook_url = "https://example.com/webhooks/qube"
+end

data/lib/generators/qube_rails/workflows_generator.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module QubeRails
+  module Generators
+    # rails g qube_rails:workflows [--drafts] [--check]
+    #
+    # Writes your app's typed workflow starts: app/qube/qube_workflows.rb (QubeWorkflows, a
+    # module per workflow with a start method per branch of its input, autoloaded from app/qube)
+    # and sig/qube_workflows.rbs, from the workflow input types QuBe Sync serves for your app's
+    # API key (config.api_key). Each start uses QubeRails.client. Check both files in, and run it
+    # again when a workflow is published.
+    #
+    # --drafts types each workflow's draft where it has one. --check writes nothing, and exits 1
+    # when the file is out of date (or QuBe Sync refuses the key), for CI; when QuBe Sync can't be
+    # reached it warns and passes.
+    class WorkflowsGenerator < Rails::Generators::Base
+      RUBY = "app/qube/qube_workflows.rb"
+      SIG = "sig/qube_workflows.rbs"
+      COMMAND = "bin/rails g qube_rails:workflows"
+      CLIENT = "::QubeRails.client"
+
+      class_option :drafts, type: :boolean, default: false,
+                            desc: "Type each workflow's draft where it has one"
+      class_option :check, type: :boolean, default: false,
+                           desc: "Write nothing; exit 1 when #{RUBY} is out of date"
+
+      def write_or_check
+        options[:check] ? check : write
+      end
+
+      private
+
+      def write
+        document = Backend.workflow_types(QubeRails.client, include_drafts: options[:drafts])
+        files = Backend.render_workflow_types(document, source: source, drafts: options[:drafts], command: COMMAND,
+                                                        client_expression: CLIENT)
+        warn_each(files.warnings)
+        create_file RUBY, files.ruby, force: true
+        create_file SIG, files.rbs, force: true
+      rescue Backend::APIError => e
+        fail_with(e.message)
+      rescue *Backend::NETWORK_ERRORS, SystemCallError => e
+        fail_with("couldn't reach QuBe Sync (#{e.class}: #{e.message}); nothing was written")
+      end
+
+      def check
+        path = File.join(destination_root, RUBY)
+        fail_with("#{RUBY} isn't there: run `#{COMMAND}` to write it") unless File.exist?(path)
+
+        result = Backend.check_workflow_types(File.read(path), client: QubeRails.client, source: source, path: RUBY,
+                                                               command: COMMAND, client_expression: CLIENT)
+        warn_each(result.warnings)
+        case result.status
+        when :current then say_status :current, result.message, :green
+        when :unreachable then say_status :warning, result.message, :yellow
+        else fail_with(result.message)
+        end
+      end
+
+      def source
+        "#{QubeRails.config.base_url.to_s.sub(%r{/+\z}, '')}/api/v2/workflows/types"
+      end
+
+      def warn_each(warnings)
+        warnings.each { |warning| say_status :warning, warning, :yellow }
+      end
+
+      # A failing check stops the command with status 1, so CI fails.
+      def fail_with(message)
+        say_status :error, message, :red
+        exit 1
+      end
+    end
+  end
+end

data/lib/qube_rails/backend.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "qube_sync/webhooks"
+require "qube_sync/client"
+
+module QubeRails
+  # Every call qube_rails makes to the qube_sync gem goes through here, and nowhere else: the
+  # client, verifying and parsing a webhook, and the errors they raise. An app on a Ruby the gem
+  # doesn't run on (it needs 3.3) gets a copy of qube_rails whose Backend does the same inline,
+  # with Net::HTTP and OpenSSL, so the rest of these files stay the same in both.
+  #
+  # What the rest of qube_rails relies on:
+  # - client(api_key:, base_url:, on_retry:) answers create_connection, update_connection,
+  #   regenerate_onboarding, start_run, answer and search as QubeSync::Client does, returning the
+  #   response's data, and raises APIError (status, body) for anything outside 2xx;
+  # - verify(raw_body, header, secrets:) raises SignatureError (with a reason: missing, malformed,
+  #   stale or mismatch) unless the delivery checks out;
+  # - parse(raw_body) returns the typed event (QubeSync::Webhooks' WorkflowRunEvent,
+  #   NotificationEvent, ConnectionEvent and the rest), raising ParseError for a body that isn't
+  #   a JSON object;
+  # - workflow_types(client, include_drafts:, etag:), render_workflow_types(document, ...) and
+  #   check_workflow_types(existing, ...) are `bin/rails g qube_rails:workflows`'s: the app's
+  #   workflow input types as QuBe Sync serves them, rendered into app/qube/qube_workflows.rb and
+  #   its RBS, and compared with a written file (QubeSync::WorkflowTypes). They need the gem's
+  #   renderer, so the inline backend raises for them, saying typed workflows need the qube_sync
+  #   gem (Ruby 3.3).
+  module Backend
+    APIError = QubeSync::APIError
+    SignatureError = QubeSync::Webhooks::SignatureError
+    ParseError = QubeSync::Webhooks::ParseError
+    # What a call that got no answer raises (a timeout, a refused or dropped connection).
+    NETWORK_ERRORS = QubeSync::Client::NETWORK_ERRORS
+
+    module_function
+
+    def client(api_key:, base_url:, on_retry: nil)
+      QubeSync::Client.new(api_key: api_key, base_url: base_url, on_retry: on_retry)
+    end
+
+    def verify(raw_body, header, secrets:)
+      QubeSync::Webhooks.verify(raw_body, header, secrets: secrets)
+    end
+
+    def parse(raw_body)
+      QubeSync::Webhooks.parse(raw_body)
+    end
+
+    # The app's workflow types document, or :not_modified when etag (its digest) is still current.
+    def workflow_types(client, include_drafts: false, etag: nil)
+      client.workflow_types(include_drafts: include_drafts, etag: etag)
+    end
+
+    # The Ruby and the RBS for a document (ruby, rbs, digest, drafts, warnings). source is the URL
+    # the header names, command the one it says to run again, client_expression what a start's
+    # client defaults to.
+    def render_workflow_types(document, source:, drafts:, command:, client_expression:)
+      require "qube_sync/workflow_types"
+      QubeSync::WorkflowTypes.render(document, source: source, drafts: drafts, command: command,
+                                               client: client_expression)
+    end
+
+    # A written file (its Ruby source) against what QuBe Sync serves now: status (:current,
+    # :stale, :unreachable or :error), message, changes, warnings and exit_status.
+    def check_workflow_types(existing, client:, source:, path:, command:, client_expression:)
+      require "qube_sync/workflow_types"
+      QubeSync::WorkflowTypes.check(existing, client: client, source: source, path: path, command: command,
+                                              client_expression: client_expression)
+    end
+  end
+end

data/lib/qube_rails/cache_dedupe.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module QubeRails
+  # A dedupe setting for an app that would rather not use the engine's table
+  # (QubeRails::DatabaseDedupe, the default): the notification delivery ids already taken, in
+  # Rails.cache, for a day. It needs a store your workers share (Redis, Solid Cache): with a
+  # per-process store (memory, or the file store on more than one machine) a retry that reaches
+  # another worker isn't caught, and the null store remembers nothing. It isn't transactional:
+  # the id is remembered after the handler commits, so a crash between the two runs the handler
+  # again on the redelivery.
+  #   config.dedupe = QubeRails::CacheDedupe.new(Rails.cache, expires_in: 1.day)
+  class CacheDedupe
+    DAY = 24 * 60 * 60
+
+    def initialize(cache = nil, expires_in: DAY)
+      @cache = cache
+      @expires_in = expires_in
+    end
+
+    def seen?(key)
+      cache.exist?(key)
+    end
+
+    def remember(key)
+      cache.write(key, true, expires_in: @expires_in)
+    end
+
+    private
+
+    def cache
+      @cache || Rails.cache
+    end
+  end
+end