qube_rails 0.2.0

data/lib/qube_rails/request.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module QubeRails
+  # One v2 operation your app queues itself, with no workflow, and what it does with that
+  # request's webhooks. Subclass it once per request, list it in config.operations by its SLUG,
+  # and see the README's "Plain requests".
+  #
+  #   class FindCustomer < QubeRails::Request
+  #     OPERATION = "customer.query"
+  #     SLUG = "find_customer"
+  #
+  #     def params
+  #       { full_name: record.name }
+  #     end
+  #
+  #     def answered(event) ... end
+  #   end
+  #
+  #   row = QuickbooksDesktop::FindCustomer.queue(customer, connection)
+  class Request
+    # The QubeRails::QueuedRequest for record on connection. While the last one hasn't ended it's
+    # returned (reused?), sent again first if QuBe Sync never confirmed it.
+    def self.queue(record, connection)
+      unless made_by_qube_sync?(connection)
+        raise NotConnected, "QuBe Sync: #{name}.queue needs a connection QuBe Sync has made (one with a " \
+                            "qube_id): the customer finishes onboarding first"
+      end
+
+      row, params_error = claim(record, connection)
+      raise params_error if params_error
+      return retry_queue(row) if row.reused?
+
+      send_queue(row)
+    end
+
+    # Sends a queue that got no answer again, with the same params and Idempotency-Key.
+    def self.retry_queue(row)
+      return row if row.qube_id
+      unless row.state == "queued"
+        raise ArgumentError, "QuBe Sync: request #{row.id} is #{row.state}: only a queue that got no answer is sent again"
+      end
+
+      send_queue(row)
+    end
+
+    # Under the connection row's lock, so a double click finds the same row.
+    def self.claim(record, connection)
+      connection.with_lock do
+        going = QubeRails::QueuedRequest.where(connection: connection).latest_for(record, self::SLUG)
+        next [going.tap { |row| row.reused = true }, nil] if going && !going.ended?
+
+        new_row(record, connection)
+      end
+    end
+    private_class_method :claim
+
+    def self.new_row(record, connection)
+      row = QubeRails::QueuedRequest.new(
+        connection: connection, operation: self::SLUG, record: record,
+        reference: "#{self::SLUG}-#{record.id}-#{SecureRandom.uuid}", state: "queued"
+      )
+      begin
+        # As JSON reads it back, so a resend sends exactly what the first did.
+        row.params = JSONCoder.load(JSONCoder.dump(new(record, row).params))
+      rescue StandardError, NotImplementedError => e
+        row.state = "failed"
+        row.ended_at = Time.now
+        row.save!
+        return [row, e]
+      end
+      row.save!
+      [row, nil]
+    end
+    private_class_method :new_row
+
+    def self.send_queue(row)
+      answer =
+        begin
+          QubeRails.client.queue(self::OPERATION, row.connection.qube_id, row.params || {},
+                                 webhook_url: row.webhook_url, idempotency_key: row.reference)
+        rescue Backend::APIError => e
+          mark_failed(row) if refused?(e)
+          raise
+        end
+      record_queue(row, answer.is_a?(Hash) ? answer : {})
+      row
+    end
+    private_class_method :send_queue
+
+    # A 4xx but 409 (the key in use by a call still in flight): nothing was queued.
+    def self.refused?(error)
+      error.status.between?(400, 499) && error.status != 409
+    end
+    private_class_method :refused?
+
+    def self.mark_failed(row)
+      now = Time.now
+      row.update_columns(state: "failed", ended_at: now, updated_at: now)
+    end
+    private_class_method :mark_failed
+
+    def self.record_queue(row, answer)
+      row.with_lock do
+        row.qube_id ||= answer["id"]
+        row.save!
+      end
+    end
+    private_class_method :record_queue
+
+    def self.made_by_qube_sync?(connection)
+      connection.is_a?(QubeRails::Connection) && !connection.qube_id.to_s.empty?
+    end
+    private_class_method :made_by_qube_sync?
+
+    # Write it to load the record your own way; left out, the row's record_type finds it.
+    def self.find_record(id)
+      raise NotImplementedError, "#{name}.find_record(#{id.inspect}) isn't written"
+    end
+
+    def self.record_for(row)
+      if method(:find_record).owner == QubeRails::Request.singleton_class
+        row.record
+      else
+        find_record(row.record_id)
+      end
+    end
+
+    attr_reader :record, :queued_request
+
+    def initialize(record, queued_request)
+      @record = record
+      @queued_request = queued_request
+    end
+
+    def connection
+      queued_request.connection
+    end
+
+    # The operation's params, from the record.
+    def params
+      raise NotImplementedError, "#{self.class.name}#params isn't written yet"
+    end
+
+    # One response_received page: event.response_json["data"], event.page.
+    def answered(event)
+      log_event(event)
+    end
+
+    # Every page 1..N answered. Called once.
+    def done; end
+
+    # error or discarded: event.error["user_message"] is safe to show.
+    def failed(event)
+      log_event(event)
+    end
+
+    # QuBe Sync keeps trying: show event.error["user_message"], never resend.
+    def retrying(event)
+      log_event(event)
+    end
+
+    # QuickBooks may have applied it. A query can be queued again; check a write first.
+    def timed_out(event)
+      failed(event)
+    end
+
+    # One webhook, from the job, under the row's lock. Deliveries come at least once, in any order.
+    def handle(event)
+      changed = false
+      queued_request.with_lock { changed = apply(event) }
+      QubeRails.broadcast_refresh(record) if changed
+    end
+
+    private
+
+    FINAL_STATES = %w[error timed_out discarded].freeze
+    private_constant :FINAL_STATES
+
+    def apply(event)
+      row = queued_request
+      unless this_request?(event)
+        QubeRails.logger.warn("QuBe Sync: #{self.class.name} request #{row.id} skipped #{event.type} " \
+                              "#{event["id"].inspect}: not this request")
+        return false
+      end
+      return false unless take_once(event)
+
+      row.qube_id ||= event.id
+      case event.state
+      when "response_received" then page_answered(event)
+      when "retryable" then retryable(event)
+      when *FINAL_STATES then final(event)
+      else
+        QubeRails.logger.warn("QuBe Sync: #{self.class.name} request #{row.id}: unknown state #{event.state.inspect}")
+      end
+      row.save!
+      true
+    end
+
+    # Request events carry no connection id: the id is checked once the row has one.
+    def this_request?(event)
+      return false unless event.type == "request"
+
+      qube_id = queued_request.qube_id
+      qube_id.nil? || event.id == qube_id
+    end
+
+    # Records the delivery in this transaction: false for one taken already.
+    def take_once(event)
+      deliveries = QubeRails::RequestDelivery.where(request_id: queued_request.id)
+      key = event.dedupe_key.to_s
+      return false if deliveries.where(dedupe_key: key).exists?
+
+      QubeRails::RequestDelivery.transaction(requires_new: true) do
+        deliveries.create!(dedupe_key: key, page: page_of(event), state: event.state.to_s)
+      end
+      true
+    rescue ActiveRecord::RecordNotUnique
+      false
+    end
+
+    def page_answered(event)
+      row = queued_request
+      row.last_page = page_of(event) if %w[done not_applicable].include?(event.iteration_state)
+      row.state = "response_received" unless row.ended?
+      answered(event)
+
+      pages = answered_pages
+      row.pages_answered = pages.size
+      return if row.ended? || row.last_page.nil?
+      return unless pages.count { |page| page.between?(1, row.last_page) } == row.last_page
+
+      row.ended_at = Time.now
+      done
+    end
+
+    def retryable(event)
+      row = queued_request
+      if page_settled?(event)
+        QubeRails.logger.info("QuBe Sync: #{self.class.name} request #{row.id} page #{page_of(event)}: " \
+                              "skipped a retryable that came after its answer")
+        return
+      end
+      unless row.ended?
+        row.state = "retryable"
+        row.error = event.error
+      end
+      retrying(event)
+    end
+
+    def final(event)
+      row = queued_request
+      unless row.ended?
+        row.state = event.state
+        row.error = event.error
+        row.ended_at = Time.now
+      end
+      event.state == "timed_out" ? timed_out(event) : failed(event)
+    end
+
+    def answered_pages
+      QubeRails::RequestDelivery.where(request_id: queued_request.id, state: "response_received")
+                                .distinct.pluck(:page).compact
+    end
+
+    def page_settled?(event)
+      QubeRails::RequestDelivery.where(request_id: queued_request.id, page: page_of(event))
+                                .where.not(state: "retryable").exists?
+    end
+
+    # An answer that wasn't paged is page 1.
+    def page_of(event)
+      event.page.is_a?(Integer) ? event.page : 1
+    end
+
+    def log_event(event)
+      code = event.error.is_a?(Hash) ? " #{event.error["error_code"] || event.error["error_type"]}" : ""
+      line = "QuBe Sync: #{self.class.name} #{record.id} (request #{queued_request.id}): " \
+             "#{event.state} page #{page_of(event)}#{code}"
+      if event.state == "response_received"
+        QubeRails.logger.info(line)
+      else
+        QubeRails.logger.warn(line)
+      end
+    end
+  end
+end

data/lib/qube_rails/rows_view.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+
+module QubeRails
+  # A rows field (add_transaction's question about missing records): the same columns asked of
+  # each row, posted as data[<field>][<row key>][<column>]. Shown as one block per record, its
+  # fields stacked: columns are FieldViews (one per column), rows RowViews. set_all is the column
+  # the "Set all to:" line sets on every row (a segmented one asked by two rows or more), or nil.
+  class RowsView
+    attr_reader :name, :label, :input_name, :search_url, :columns, :rows
+
+    def initialize(field, input_name:, search_url:)
+      @name = field["name"].to_s
+      @label = (field["label"] || @name).to_s
+      @input_name = input_name
+      @search_url = search_url
+      declared = Array(field["columns"]).select { |c| c.is_a?(Hash) }
+      @columns = declared.map { |column| column_field(column) }
+      @rows = Array(field["rows"]).select { |r| r.is_a?(Hash) }.each_with_index.map do |row, n|
+        RowView.new(row, declared, self, n)
+      end
+    end
+
+    # A column's control for one row (context :cell). Shown or not, it isn't required in the
+    # markup while hidden (the script sets required as it shows it).
+    def cell_field(column, row_key, row_index, shown)
+      col = column["name"].to_s
+      FieldView.new(name: col, type: FieldView.type_of(column, record_type: "search"),
+                    label: column["label"] || col, input_name: "#{input_name}[#{row_key}][#{col}]",
+                    dom_id: "qube-#{input_name.gsub(/[^A-Za-z0-9]+/, "-")}#{row_index}-#{col}".squeeze("-"),
+                    required: column["required"] == true && shown, options: FieldView.options_of(column),
+                    kind: column["kind"], search_url: search_url, search_field: "#{name}.#{col}",
+                    row_key: row_key, when_values: when_of(column), context: :cell, disabled: !shown)
+    end
+
+    def when_of(column)
+      column["when"].is_a?(Hash) ? column["when"] : {}
+    end
+
+    # The column "Set all to:" sets, with its options: the first segmented one two rows or more ask.
+    def set_all
+      return nil if rows.size < 2
+
+      columns.find do |column|
+        column.type == "select" && column.options.size.between?(1, 3) &&
+          rows.count { |row| row.cells.any? { |cell| cell.column == column.name && cell.field } } >= 2
+      end
+    end
+
+    private
+
+    def column_field(column)
+      col = column["name"].to_s
+      FieldView.new(name: col, type: FieldView.type_of(column, record_type: "search"), label: column["label"] || col,
+                    required: column["required"] == true, options: FieldView.options_of(column),
+                    kind: column["kind"], search_url: search_url, search_field: "#{name}.#{col}",
+                    when_values: when_of(column), context: :cell)
+    end
+  end
+
+  # One record: its cells (the columns it asks, and a value it already has), and the values it
+  # already has (values_json for data-qube-values, which a column's "when" reads with the row's
+  # answers). A column the row neither asks nor has a value for has no cell.
+  class RowView
+    attr_reader :key, :label, :detail, :values, :cells, :index
+
+    def initialize(row, declared, rows, index = 0)
+      @key = row["key"].to_s
+      @label = (row["label"] || @key).to_s
+      @detail = row["detail"].to_s.strip.empty? ? nil : row["detail"].to_s
+      @values = row["values"].is_a?(Hash) ? row["values"] : {}
+      @index = index
+      asks = Array(row["columns"]).map(&:to_s)
+      @cells = declared.filter_map do |column|
+        col = column["name"].to_s
+        when_values = rows.when_of(column)
+        shown = applies?(when_values)
+        required = column["required"] == true
+        label = (column["label"] || col).to_s
+        if asks.include?(col)
+          CellView.new(column: col, label: label, field: rows.cell_field(column, @key, index, shown),
+                       when_values: when_values, shown: shown, required: required)
+        elsif !@values[col].to_s.empty?
+          CellView.new(column: col, label: label, preset: preset_text(column, @values[col]), when_values: when_values,
+                       shown: shown)
+        end
+      end
+    end
+
+    def values_json
+      values.to_json
+    end
+
+    # The segmented cells (the row's choice, such as create or use), then the rest.
+    def segmented_cells
+      cells.select(&:segmented?)
+    end
+
+    def field_cells
+      cells.reject(&:segmented?)
+    end
+
+    private
+
+    # Before the user picks anything, a column shows when its "when" holds for the row's values.
+    def applies?(when_values)
+      when_values.all? { |col, allowed| Array(allowed).include?(values[col]) }
+    end
+
+    # A value the row already has, shown as its enum label when it has one.
+    def preset_text(column, value)
+      entry = Array(column["enum"]).find { |e| e.is_a?(Hash) && e["value"] == value }
+      entry ? entry["label"].to_s : value.to_s
+    end
+  end
+
+  # One field of a row: a field to fill (field), or what the row already has (preset, read-only).
+  # A cell whose "when" doesn't hold yet is hidden (shown false: hidden, data-qube-hidden, its input
+  # disabled and not required). required is the column's, which the script restores as it shows it.
+  class CellView
+    attr_reader :column, :label, :field, :preset, :when, :shown, :required
+
+    def initialize(column:, label: nil, field: nil, preset: nil, when_values: {}, shown: true, required: false)
+      @column = column
+      @label = label || column
+      @field = field
+      @preset = preset
+      @when = when_values
+      @shown = shown
+      @required = required
+    end
+
+    def when_json
+      self.when.to_json
+    end
+
+    def hidden?
+      !shown
+    end
+
+    def segmented?
+      !field.nil? && field.segmented?
+    end
+  end
+end

data/lib/qube_rails/run_status_view.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module QubeRails
+  # Where a record stands, as the run status partials render it: the override contract, kept
+  # stable across versions (README, "Styling"). status is QubeRails::SyncStatus's (:not_sent,
+  # :sending, :needs_answer, :in_quickbooks, :done, :failed, :cancelled); state the latest run's
+  # ("starting", "running", "awaiting_input", "completed", "failed" or "cancelled"), or nil.
+  # summary is a few words for the pill; reason, why it failed or was cancelled, as a sentence
+  # below it; detail, what to do about a failure.
+  class RunStatusView
+    attr_reader :status, :state, :summary, :reason, :detail, :quiet_text, :retry_url, :redeliver_url, :error, :stall,
+                :stall_text
+
+    # The stall reasons with words of their own (status.stalled.<reason>); any other is "other".
+    STALL_REASONS = %w[not_checking_in quickbooks_unavailable].freeze
+
+    # From a QubeRails::SyncStatus. urls answers retry_start_path(run) and redeliver_path(run):
+    # the engine's route proxy (qube_rails) in a view. connection is the one the status is about
+    # (else the latest run's): while it's stalled, a status waiting on QuickBooks (:sending) says
+    # why (stall, stall_text) and offers no redelivery, since the cause is known.
+    def self.from_sync(sync, urls, error: nil, connection: nil)
+      run = sync.run
+      state = run && (run.cancelled? ? "cancelled" : run.state)
+      reason = run && (sync.failed? || run.cancelled?) ? run.reason_text : nil
+      detail = sync.failed? && run ? run.error_detail : nil
+      connection ||= run && run.connection
+      stall = sync.status == :sending ? stall_of(connection) : nil
+      stuck = run && !stall ? run.looks_stuck? : false
+      new(status: sync.status, state: state,
+          summary: stall ? QubeRails.t("status.waiting_for_quickbooks") : sync.summary_text, reason: reason, detail: detail,
+          quiet_text: stuck ? QubeRails.t("status.quiet") : nil,
+          retry_url: sync.unconfirmed? ? urls.retry_start_path(run) : nil,
+          redeliver_url: stuck ? urls.redeliver_path(run) : nil, error: error, stall: stall)
+    end
+
+    # A stalled connection's reason as a Symbol (:other when it gives none), or nil.
+    def self.stall_of(connection)
+      return nil unless connection && connection.status == "stalled"
+
+      reason = connection.stall_reason.to_s
+      reason.empty? ? :other : reason.to_sym
+    end
+
+    def initialize(status:, state: nil, summary: nil, reason: nil, detail: nil, quiet_text: nil, retry_url: nil,
+                   redeliver_url: nil, error: nil, stall: nil)
+      @status = status.to_sym
+      @state = state
+      @summary = summary
+      @reason = reason
+      @detail = detail
+      @quiet_text = quiet_text
+      @retry_url = retry_url
+      @redeliver_url = redeliver_url
+      @error = error
+      @stall = stall
+      @stall_text = stall && QubeRails.t("status.stalled.#{STALL_REASONS.include?(stall.to_s) ? stall : "other"}")
+    end
+
+    # Nothing is shown before the record is sent (the error aside).
+    def visible?
+      status != :not_sent
+    end
+
+    # The qube- classes on the status element: qube-sync-<status>, qube-run-<state>, and
+    # qube-connection-stalled while it waits on a stalled connection.
+    def css_class
+      ["qube-run-status", "qube-sync-#{status}", state && "qube-run-#{state}", stall && "qube-connection-stalled"]
+        .compact.join(" ")
+    end
+  end
+end

data/lib/qube_rails/storyboard/ask_about_add.json

@@ -0,0 +1,60 @@
+{
+  "title": "A lost answer",
+  "note": "add_transaction's ask_about_add: QuickBooks never answered the add, and the run couldn't settle whether it went in. Use a candidate, add it again, or cancel.",
+  "prompt": {
+    "id": "add_transaction / ask_about_add",
+    "kind": "decision",
+    "token": "Xh6rV8wBt4QjC6eE",
+    "message": "QuickBooks didn't confirm whether this invoice went in. If it's the one below, use it; if it isn't there, add it again.",
+    "data": {
+      "operation": "invoice",
+      "why": "lost_answer",
+      "candidates_complete": true,
+      "external_guid": "{6B0C3A52-6E1A-4F43-9B1F-0D3E3E1F7A10}",
+      "not_found": null
+    },
+    "details": [
+      {
+        "label": "Adding",
+        "value": "Invoice"
+      },
+      {
+        "label": "Number",
+        "value": "1042"
+      },
+      {
+        "label": "Date",
+        "value": "2026-10-20"
+      },
+      {
+        "label": "For",
+        "value": "Riverbend Electric"
+      }
+    ],
+    "options": [],
+    "choices": [
+      {
+        "id": "use_existing:1",
+        "label": "1042",
+        "description": null,
+        "detail": "2026-10-20 · Riverbend Electric · 1250.00",
+        "fields": []
+      },
+      {
+        "id": "add_again",
+        "label": "None of them: add it again",
+        "description": null,
+        "detail": null,
+        "fields": []
+      },
+      {
+        "id": "cancel",
+        "label": "Cancel",
+        "description": null,
+        "detail": null,
+        "fields": []
+      }
+    ]
+  },
+  "search": {}
+}

data/lib/qube_rails/storyboard/choose.json

@@ -0,0 +1,51 @@
+{
+  "title": "A pick from a list",
+  "note": "resolve_transaction's ask: an option whose field has choose becomes one choice per item (use:1, use:2, ...), each with its detail; the server fills the field.",
+  "prompt": {
+    "id": "resolve_transaction / ask",
+    "kind": "decision",
+    "token": "Tc7mR3sWp9KdX2yA",
+    "message": "More than one invoice could be the one you meant. Pick it, say none of these is it, or cancel.",
+    "data": {
+      "ref_number": "1042"
+    },
+    "details": [
+      {
+        "label": "Invoice",
+        "value": "1042"
+      }
+    ],
+    "options": [],
+    "choices": [
+      {
+        "id": "use:1",
+        "label": "1042",
+        "description": null,
+        "detail": "2026-10-20 · Riverbend Electric · 1250.00",
+        "fields": []
+      },
+      {
+        "id": "use:2",
+        "label": "1042-B",
+        "description": null,
+        "detail": "2026-10-21 · Riverbend Electric · 310.50",
+        "fields": []
+      },
+      {
+        "id": "none",
+        "label": "None of these",
+        "description": null,
+        "detail": null,
+        "fields": []
+      },
+      {
+        "id": "cancel",
+        "label": "Cancel",
+        "description": null,
+        "detail": null,
+        "fields": []
+      }
+    ]
+  },
+  "search": {}
+}

data/lib/qube_rails/storyboard/enum_select.json

@@ -0,0 +1,56 @@
+{
+  "title": "A fixed list",
+  "note": "A string field with an enum shows as a select, a blank first; the answer is the picked value. No shipped template asks one; a chart of your own can.",
+  "prompt": {
+    "id": "route_order / ask_route",
+    "kind": "decision",
+    "token": "Ue2nS5tYq1MfZ3bB",
+    "message": "Which list should this order go to?",
+    "data": {},
+    "details": [
+      {
+        "label": "Order",
+        "value": "SO-2207"
+      }
+    ],
+    "options": [],
+    "choices": [
+      {
+        "id": "route",
+        "label": "Send it",
+        "description": null,
+        "detail": null,
+        "fields": [
+          {
+            "name": "destination",
+            "type": "string",
+            "label": "Goes to",
+            "required": true,
+            "enum": [
+              {
+                "value": "sales_order",
+                "label": "Sales order"
+              },
+              {
+                "value": "estimate",
+                "label": "Estimate"
+              },
+              {
+                "value": "invoice",
+                "label": "Invoice"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "id": "cancel",
+        "label": "Cancel",
+        "description": null,
+        "detail": null,
+        "fields": []
+      }
+    ]
+  },
+  "search": {}
+}