qube_rails 0.2.0

data/lib/qube_rails/storyboard/rows.json

@@ -0,0 +1,359 @@
+{
+  "title": "Records not in QuickBooks yet",
+  "note": "add_transaction's ask_missing: a block per missing record, its fields stacked, each shown while its \"when\" holds. Hardware Kit's add says it's an inventory part, so its type is shown, not asked. \"Set all to:\" sets every record's choice; \"Use for all\" copies a picked value to the others.",
+  "prompt": {
+    "id": "add_transaction / ask_missing",
+    "kind": "decision",
+    "token": "Yj7sW9xCu5RkD7fF",
+    "message": "Some records this transaction uses aren't in QuickBooks yet. For each one, create it or pick one QuickBooks already has.",
+    "data": {
+      "operation": "invoice",
+      "missing": [
+        {
+          "kind": "customer",
+          "full_name": "Lone Star Supply",
+          "paths": [
+            "customer_ref"
+          ]
+        },
+        {
+          "kind": "item",
+          "full_name": "Vinyl Banner 3x6",
+          "paths": [
+            "invoice_line_add.0.item_ref"
+          ]
+        },
+        {
+          "kind": "item",
+          "full_name": "Hardware Kit",
+          "paths": [
+            "invoice_line_add.1.item_ref"
+          ]
+        }
+      ]
+    },
+    "details": [
+      {
+        "label": "Adding",
+        "value": "Invoice"
+      },
+      {
+        "label": "Number",
+        "value": "1042"
+      },
+      {
+        "label": "For",
+        "value": "Lone Star Supply"
+      }
+    ],
+    "options": [],
+    "choices": [
+      {
+        "id": "proceed",
+        "label": "Add the transaction",
+        "description": null,
+        "detail": null,
+        "fields": [
+          {
+            "name": "records",
+            "type": "rows",
+            "label": "Not in QuickBooks yet",
+            "required": true,
+            "columns": [
+              {
+                "name": "action",
+                "type": "string",
+                "label": "What to do",
+                "required": true,
+                "kind": null,
+                "enum": [
+                  {
+                    "value": "create",
+                    "label": "Create it"
+                  },
+                  {
+                    "value": "use",
+                    "label": "Use an existing one"
+                  }
+                ],
+                "when": null
+              },
+              {
+                "name": "list_id",
+                "type": "record",
+                "label": "Existing record",
+                "required": true,
+                "kind": null,
+                "enum": null,
+                "when": {
+                  "action": [
+                    "use"
+                  ]
+                }
+              },
+              {
+                "name": "item_type",
+                "type": "string",
+                "label": "Item type",
+                "required": true,
+                "kind": null,
+                "enum": [
+                  {
+                    "value": "item_service",
+                    "label": "Service"
+                  },
+                  {
+                    "value": "item_non_inventory",
+                    "label": "Non-inventory part"
+                  },
+                  {
+                    "value": "item_inventory",
+                    "label": "Inventory part"
+                  },
+                  {
+                    "value": "item_other_charge",
+                    "label": "Other charge"
+                  }
+                ],
+                "when": {
+                  "action": [
+                    "create"
+                  ]
+                }
+              },
+              {
+                "name": "entity_type",
+                "type": "string",
+                "label": "Add it as",
+                "required": true,
+                "kind": null,
+                "enum": [
+                  {
+                    "value": "customer",
+                    "label": "Customer"
+                  },
+                  {
+                    "value": "vendor",
+                    "label": "Vendor"
+                  },
+                  {
+                    "value": "other_name",
+                    "label": "Other name"
+                  }
+                ],
+                "when": {
+                  "action": [
+                    "create"
+                  ]
+                }
+              },
+              {
+                "name": "income_account",
+                "type": "record",
+                "label": "Income account",
+                "required": true,
+                "kind": "account",
+                "enum": null,
+                "when": {
+                  "action": [
+                    "create"
+                  ]
+                }
+              },
+              {
+                "name": "asset_account",
+                "type": "record",
+                "label": "Inventory asset account",
+                "required": true,
+                "kind": "account",
+                "enum": null,
+                "when": {
+                  "action": [
+                    "create"
+                  ],
+                  "item_type": [
+                    "item_inventory"
+                  ]
+                }
+              },
+              {
+                "name": "cogs_account",
+                "type": "record",
+                "label": "Cost of goods sold account",
+                "required": true,
+                "kind": "account",
+                "enum": null,
+                "when": {
+                  "action": [
+                    "create"
+                  ],
+                  "item_type": [
+                    "item_inventory"
+                  ]
+                }
+              }
+            ],
+            "rows": [
+              {
+                "key": "customer_ref",
+                "label": "Lone Star Supply",
+                "detail": "Customer",
+                "columns": [
+                  "action",
+                  "list_id"
+                ],
+                "values": {},
+                "kinds": {
+                  "list_id": "customer"
+                }
+              },
+              {
+                "key": "invoice_line_add.0.item_ref",
+                "label": "Vinyl Banner 3x6",
+                "detail": "Item",
+                "columns": [
+                  "action",
+                  "list_id",
+                  "item_type",
+                  "income_account",
+                  "asset_account",
+                  "cogs_account"
+                ],
+                "values": {},
+                "kinds": {
+                  "list_id": "item",
+                  "income_account": "account",
+                  "asset_account": "account",
+                  "cogs_account": "account"
+                }
+              },
+              {
+                "key": "invoice_line_add.1.item_ref",
+                "label": "Hardware Kit",
+                "detail": "Item",
+                "columns": [
+                  "action",
+                  "list_id",
+                  "income_account",
+                  "asset_account",
+                  "cogs_account"
+                ],
+                "values": {
+                  "item_type": "item_inventory"
+                },
+                "kinds": {
+                  "list_id": "item",
+                  "income_account": "account",
+                  "asset_account": "account",
+                  "cogs_account": "account"
+                }
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "id": "cancel",
+        "label": "Cancel",
+        "description": "Stop here. Nothing is created.",
+        "detail": null,
+        "fields": []
+      }
+    ]
+  },
+  "search": {
+    "records.list_id": [
+      {
+        "value": "80000001-1700000000",
+        "label": "Riverbend Electric",
+        "detail": "Customer"
+      },
+      {
+        "value": "80000002-1700000000",
+        "label": "Riverbend Supply Co.",
+        "detail": "Customer"
+      },
+      {
+        "value": "80000003-1700000000",
+        "label": "Lone Star Supply",
+        "detail": "Customer"
+      },
+      {
+        "value": "80000011-1700000000",
+        "label": "Vinyl Banner 3x6",
+        "detail": "Inventory part"
+      },
+      {
+        "value": "80000012-1700000000",
+        "label": "Hardware Kit",
+        "detail": "Non-inventory part"
+      }
+    ],
+    "records.income_account": [
+      {
+        "value": "8000000A-1700000000",
+        "label": "Sales",
+        "detail": "Income"
+      },
+      {
+        "value": "8000000B-1700000000",
+        "label": "Sales:Signs",
+        "detail": "Income"
+      },
+      {
+        "value": "80000005-1700000000",
+        "label": "Inventory Asset",
+        "detail": "Other current asset"
+      },
+      {
+        "value": "80000006-1700000000",
+        "label": "Cost of Goods Sold",
+        "detail": "Cost of goods sold"
+      }
+    ],
+    "records.asset_account": [
+      {
+        "value": "8000000A-1700000000",
+        "label": "Sales",
+        "detail": "Income"
+      },
+      {
+        "value": "8000000B-1700000000",
+        "label": "Sales:Signs",
+        "detail": "Income"
+      },
+      {
+        "value": "80000005-1700000000",
+        "label": "Inventory Asset",
+        "detail": "Other current asset"
+      },
+      {
+        "value": "80000006-1700000000",
+        "label": "Cost of Goods Sold",
+        "detail": "Cost of goods sold"
+      }
+    ],
+    "records.cogs_account": [
+      {
+        "value": "8000000A-1700000000",
+        "label": "Sales",
+        "detail": "Income"
+      },
+      {
+        "value": "8000000B-1700000000",
+        "label": "Sales:Signs",
+        "detail": "Income"
+      },
+      {
+        "value": "80000005-1700000000",
+        "label": "Inventory Asset",
+        "detail": "Other current asset"
+      },
+      {
+        "value": "80000006-1700000000",
+        "label": "Cost of Goods Sold",
+        "detail": "Cost of goods sold"
+      }
+    ]
+  }
+}

data/lib/qube_rails/storyboard.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "json"
+
+module QubeRails
+  # Every screen the engine's partials show, from sample data, for GET qube/storyboard: the run
+  # status in each state, the one-shot error, and a question of each kind (lib/qube_rails/
+  # storyboard/*.json, prompts shaped as QuBe Sync sends them). Nothing is read from or written
+  # to QuBe Sync or the database: runs are built, never saved.
+  module Storyboard
+    DIR = File.expand_path("storyboard", __dir__)
+
+    Screen = Struct.new(:key, :group, :title, :note, :partials, :kind, :sample)
+
+    QUESTIONS = %w[near_match record_search choose enum_select number_boolean name_clash ask_about_add missing_record rows
+                   refusal].freeze
+
+    # key, title, SyncStatus status, the run's attributes (ages in seconds), extra pieces, note.
+    RUN_STATUSES = [
+      ["not_sent", "Not sent", :not_sent, nil, [],
+       "A record with no run: the run status partial renders nothing."],
+      ["starting", "Starting", :sending, { state: "starting", age: 5 }, [],
+       "A start QuBe Sync is confirming."],
+      ["unconfirmed", "A start not confirmed", :sending, { state: "starting", age: 120 }, ["run_status/retry"],
+       "QuBe Sync hasn't confirmed the start for a minute: the retry button sends it again, same reference."],
+      ["running", "Running", :sending, { state: "running", qube_run_id: "run-sample", age: 30 }, [],
+       "QuBe Sync confirmed it; the Web Connector is working through it."],
+      ["stalled_not_checking_in", "Waiting: QuickBooks isn't checking in", :sending,
+       { state: "running", qube_run_id: "run-sample", age: 30 * 60, stall: "not_checking_in" }, ["run_status/stall"],
+       "A run going on a connection QuBe Sync says stalled (not_checking_in): the Web Connector hasn't called in. " \
+       "No redeliver button: the cause is known."],
+      ["stalled_quickbooks_unavailable", "Waiting: QuickBooks is closed", :sending,
+       { state: "running", qube_run_id: "run-sample", age: 30 * 60, stall: "quickbooks_unavailable" },
+       ["run_status/stall"],
+       "The same, stalled as quickbooks_unavailable: the Web Connector calls in but can't open the company file."],
+      ["needs_answer", "Waiting for an answer", :needs_answer,
+       { state: "awaiting_input", qube_run_id: "run-sample", age: 30, question: { "message" => "?" } }, [],
+       "The run asks a question: the question partial shows it (below)."],
+      ["looks_stuck", "Looks stuck", :sending, { state: "running", qube_run_id: "run-sample", age: 15 * 60 },
+       ["run_status/redeliver"],
+       "No news for 10 minutes: the redeliver button asks QuBe Sync to send its latest event again."],
+      ["in_quickbooks", "In QuickBooks", :in_quickbooks, { state: "completed", outcome: "added", ended: true }, [],
+       "The record is linked to its QuickBooks id."],
+      ["done", "Done", :done, { state: "completed", outcome: "completed", ended: true }, [],
+       "Completed, linking nothing (an operation that doesn't link its record)."],
+      ["failed", "Failed", :failed,
+       { state: "failed", ended: true,
+         error: { "message" => "QuickBooks refused the invoice because Riverbend Electric is inactive",
+                  "detail" => "Make Riverbend Electric active in QuickBooks, then send it again." } },
+       ["run_status/detail"], "A failure: the pill says it couldn't sync; below it, why (the error's message) and what to do (its detail)."],
+      ["cancelled", "Cancelled", :cancelled,
+       { state: "cancelled", ended: true, cancel_reason: "The order was cancelled in the app." }, [],
+       "Cancelled by your app, with its reason."]
+    ].freeze
+
+    # Stands in for the engine's routes: every form posts to the storyboard's no-op answer.
+    class Urls
+      def initialize(answer_path)
+        @answer_path = answer_path
+      end
+
+      def question_path(_run)
+        @answer_path
+      end
+
+      def retry_start_path(_run)
+        @answer_path
+      end
+
+      def redeliver_path(_run)
+        @answer_path
+      end
+    end
+
+    class << self
+      def screens
+        run_status_screens + [error_screen] + QUESTIONS.map { |key| question_screen(key) }
+      end
+
+      def find(key)
+        screens.find { |screen| screen.key == key.to_s }
+      end
+
+      def run_status_view(screen, urls)
+        RunStatusView.from_sync(sync_status(screen.sample), urls)
+      end
+
+      def question_view(screen, answer_path, search_path)
+        QuestionView.new(screen.sample["prompt"], action_url: answer_path, search_url: search_path,
+                                                  error: screen.sample["error"])
+      end
+
+      # The sample's matches for a search: at most 20 whose label holds q.
+      def matches(screen, field, q)
+        list = screen && screen.kind == :question ? Array(screen.sample["search"][field.to_s]) : []
+        q = q.to_s.strip.downcase
+        list.select { |m| m["label"].to_s.downcase.include?(q) }.first(20)
+      end
+
+      # The file an app puts at that path to override a piece.
+      def override_path(partial)
+        dir, _, name = partial.rpartition("/")
+        "app/views/qube_rails/#{dir.empty? ? "" : "#{dir}/"}_#{name}.html.erb"
+      end
+
+      private
+
+      def run_status_screens
+        RUN_STATUSES.map do |key, title, status, run, pieces, note|
+          partials = %w[run_status/status run_status/summary] + pieces
+          partials = [] if status == :not_sent
+          Screen.new(key, "Run status", title, note, partials, :run_status, { status: status, run: run })
+        end
+      end
+
+      def error_screen
+        Screen.new("error", "Run status", "A one-shot error",
+                   "A route's message (flash[:qube_rails_error]), shown once by whichever partial comes first, " \
+                   "or by render \"qube_rails/error\" on a page without them.", ["error"], :error,
+                   { message: QubeRails.t("errors.question_changed") })
+      end
+
+      def question_screen(key)
+        sample = JSON.parse(File.read(File.join(DIR, "#{key}.json")))
+        Screen.new(key, "Questions", sample["title"], sample["note"], question_partials(sample), :question, sample)
+      end
+
+      def question_partials(sample)
+        prompt = sample["prompt"]
+        list = %w[question/question question/message]
+        list << "question/details" if Array(prompt["details"]).any?
+        view = QuestionView.new(prompt, action_url: "", search_url: "")
+        list.concat(%w[question/picks question/pick]) if view.picks.any?
+        list << "question/choice" if view.forms.any? || view.exits.any?
+        list << "question/footer" if view.exits.any?
+        list << "error" if sample["error"]
+        fields = Array(prompt["choices"]).flat_map { |choice| Array(choice["fields"]) }
+        fields.each do |field|
+          type = FieldView.type_of(field, record_type: "search")
+          list << "question/field" unless type == "rows"
+          list << "question/fields/#{type}"
+          next unless type == "rows"
+
+          list.concat(%w[question/rows/row question/rows/cell question/rows/segmented question/field])
+          Array(field["columns"]).each { |c| list << "question/fields/#{FieldView.type_of(c, record_type: "search")}" }
+        end
+        list.uniq
+      end
+
+      def sync_status(sample)
+        attrs = sample[:run]
+        return SyncStatus.new(:not_sent, nil, nil) unless attrs
+
+        now = Time.now
+        created = now - attrs[:age].to_i
+        run = Run.new(state: attrs[:state], outcome: attrs[:outcome], error: attrs[:error],
+                      cancel_reason: attrs[:cancel_reason], qube_run_id: attrs[:qube_run_id],
+                      question: attrs[:question], operation: "storyboard", reference: "storyboard",
+                      created_at: created, updated_at: created, ended_at: attrs[:ended] ? now : nil)
+        run.connection = Connection.new(status: attrs[:stall] ? "stalled" : "connected", stall_reason: attrs[:stall])
+        SyncStatus.new(sample[:status], run, nil)
+      end
+    end
+  end
+end

data/lib/qube_rails/sync_status.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module QubeRails
+  # Where one of your records stands with QuickBooks on one connection, for one operation,
+  # worked out from what the engine already keeps: the record's runs (qube_runs) and its
+  # QuickBooks link (qube_quickbooks_records). Nothing is stored for it, so it can't go stale,
+  # and your tables need no status column.
+  #
+  #   status = connection.sync_status(invoice, operation: "create_invoice")
+  #   status.status    # => :not_sent, :sending, :needs_answer, :in_quickbooks, :done, :failed or
+  #                    #    :cancelled
+  #   status.qb_id     # the record's QuickBooks id on this connection, when it's linked
+  #   status.error     # a failed run's error ({ "message" => ..., ... }), else nil
+  #   status.retry?    # whether starting it again makes sense
+  #
+  # Per connection: an invoice can be in one company file and not another.
+  #
+  # The run and the link can disagree (a record linked earlier, with a new run since), so the
+  # newest word wins, in this order:
+  # 1. the latest run hasn't ended: :sending (starting or running, an unconfirmed start too:
+  #    unconfirmed? says so) or :needs_answer (awaiting input), whatever the link says;
+  # 2. the latest run failed or was cancelled after the link was made (or there's no link):
+  #    :failed or :cancelled;
+  # 3. the record is linked: :in_quickbooks, always with its qb_id;
+  # 4. the latest run completed and linked nothing (an operation that doesn't link its record):
+  #    :done, which a start may follow, since nothing in QuickBooks stands for the record;
+  # 5. neither: :not_sent.
+  class SyncStatus
+    STATUSES = %i[not_sent sending needs_answer in_quickbooks done failed cancelled].freeze
+
+    attr_reader :status, :run, :link
+
+    # record's status on connection for operation (its SLUG).
+    def self.for(connection, record, operation:)
+      run = QubeRails::Run.where(connection: connection).latest_for(record, operation)
+      type, id = QubeRails::ApplicationRecord.key_for(record)
+      link = connection.quickbooks_records.where(record_type: type, record_id: id)
+                       .order(updated_at: :desc, id: :desc).first
+      new(status_of(run, link), run, link)
+    end
+
+    # record's status on the connection its latest run of operation went out on: what a record's
+    # page shows when it doesn't say which connection. :not_sent when it has no run.
+    def self.latest(record, operation:)
+      run = QubeRails::Run.latest_for(record, operation)
+      return new(:not_sent, nil, nil) unless run
+
+      self.for(run.connection, record, operation: operation)
+    end
+
+    def self.status_of(run, link)
+      return in_flight(run) if run && !run.ended?
+      return stopped(run) if stopped_since_link?(run, link)
+      return :in_quickbooks if link
+      return :done if run&.state == "completed"
+
+      :not_sent
+    end
+    private_class_method :status_of
+
+    def self.in_flight(run)
+      run.state == "awaiting_input" ? :needs_answer : :sending
+    end
+    private_class_method :in_flight
+
+    def self.stopped(run)
+      run.cancelled? ? :cancelled : :failed
+    end
+    private_class_method :stopped
+
+    # The latest run failed or was cancelled, and the link (if any) is older than its end.
+    def self.stopped_since_link?(run, link)
+      return false unless run && (run.failed? || run.cancelled?)
+
+      link.nil? || link.updated_at <= (run.ended_at || run.updated_at)
+    end
+    private_class_method :stopped_since_link?
+
+    def initialize(status, run, link)
+      @status = status
+      @run = run
+      @link = link
+    end
+
+    STATUSES.each do |name|
+      define_method(:"#{name}?") { status == name }
+    end
+
+    # The record's QuickBooks id on this connection, when it's linked.
+    def qb_id
+      link&.qb_id
+    end
+
+    # A failed run's error, as its event carried it.
+    def error
+      run&.error if failed?
+    end
+
+    # A start QuBe Sync hasn't confirmed for a minute: run.retry_start! sends it again.
+    def unconfirmed?
+      sending? && run.unconfirmed?
+    end
+
+    # Whether starting the operation again makes sense: after a failure or a cancellation, unless
+    # the record is in QuickBooks on this connection anyway (an add sent again would add it twice).
+    # Not while a run is going: a start then returns that run.
+    def retry?
+      (failed? || cancelled?) && link.nil?
+    end
+
+    # Where it stands, in one plain sentence for a person (the run's, QubeRails::Run#summary_text,
+    # when a run says it), or nil when it hasn't been sent.
+    def summary_text
+      return nil if not_sent?
+      return QubeRails.t("status.in_quickbooks") if in_quickbooks? && run&.state != "completed"
+
+      run.summary_text
+    end
+
+    def to_s
+      status.to_s
+    end
+  end
+end

data/lib/qube_rails/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module QubeRails
+  VERSION = "0.2.0"
+end

data/lib/qube_rails/view_helpers.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module QubeRails
+  # Helpers in every view of your app (the engine includes them into ActionView).
+  module ViewHelpers
+    # The question's behaviour script, and with stylesheet: true the engine's opt-in stylesheet,
+    # for your layout's <head>:
+    #   <%= qube_rails_assets stylesheet: true %>
+    # Served by your asset pipeline (Propshaft or Sprockets) as qube_rails/question.js and
+    # qube_rails.css.
+    def qube_rails_assets(stylesheet: false)
+      tags = []
+      tags << stylesheet_link_tag("qube_rails", media: "all") if stylesheet
+      tags << javascript_include_tag("qube_rails/question", defer: true, nonce: true)
+      safe_join(tags, "\n")
+    end
+
+    # The classes for a piece of the engine's screens: its qube- classes, then the app's
+    # config.ui_classes for that piece.
+    def qube_classes(piece, *base)
+      extra = QubeRails.config.ui_classes[piece.to_sym]
+      unless QubeRails::Configuration::UI_PIECES.include?(piece.to_sym)
+        raise ArgumentError, "QuBe Sync: no ui_classes piece #{piece.inspect}"
+      end
+
+      (base.flatten.compact + [extra]).reject { |c| c.nil? || c.empty? }.join(" ")
+    end
+  end
+end