spree_square 0.1.0

data/app/jobs/spree_square/inventory_webhook_job.rb

@@ -0,0 +1,27 @@
+module SpreeSquare
+  # Handles `inventory.count.updated`. Unlike the catalog webhook, this
+  # payload is fully actionable on its own — catalog_object_id, location_id,
+  # and the new quantity all arrive inline, no follow-up API call needed.
+  class InventoryWebhookJob < BaseJob
+    retry_on StandardError, wait: :polynomially_longer, attempts: 5 do |job, error|
+      SpreeSquare::WebhookEvent.find_by(id: job.arguments.first)&.mark_failed!(error)
+      SpreeSquare::Alerting.capture(error, context: 'inventory_webhook')
+    end
+
+    def perform(webhook_event_id)
+      event = SpreeSquare::WebhookEvent.find(webhook_event_id)
+
+      counts = event.payload.dig('data', 'object', 'inventory_counts') || []
+      counts.each do |count|
+        SpreeSquare::InventorySync.call(
+          catalog_object_id: count['catalog_object_id'],
+          location_id: count['location_id'],
+          quantity: count['quantity'],
+          state: count['state']
+        )
+      end
+
+      event.mark_processed!
+    end
+  end
+end

data/app/jobs/spree_square/order_push_job.rb

@@ -0,0 +1,23 @@
+module SpreeSquare
+  # A failed order push is the worst failure mode in this whole system —
+  # payment already taken, kitchen never sees the ticket. Retries with
+  # backoff; if genuinely exhausted, this is the one alert in the whole
+  # extension that should always reach a human regardless of Sentry config,
+  # which is why Alerting always logs at error level even when Sentry isn't
+  # available.
+  class OrderPushJob < BaseJob
+    retry_on StandardError, wait: :polynomially_longer, attempts: 5 do |job, error|
+      order = Spree::Order.find_by(id: job.arguments.first)
+      SpreeSquare::OrderMapping.find_or_initialize_by(order: order).mark_failed!(error) if order
+      SpreeSquare::Alerting.capture(
+        error,
+        context: { area: 'order_push', order_number: order&.number }
+      )
+    end
+
+    def perform(order_id)
+      order = Spree::Order.find(order_id)
+      SpreeSquare::OrderPusher.call(order)
+    end
+  end
+end

data/app/jobs/spree_square/order_webhook_job.rb

@@ -0,0 +1,51 @@
+module SpreeSquare
+  # Handles `order.updated` and `order.fulfillment.updated`. Payload shapes
+  # verified against real Square test webhooks (not assumed from docs):
+  #
+  #   order.updated:            data.object.order_updated
+  #                              { order_id, state, version, ... }
+  #   order.fulfillment.updated: data.object.order_fulfillment_updated
+  #                              { order_id, version, fulfillment_update:
+  #                                [{ fulfillment_uid, new_state, old_state }] }
+  class OrderWebhookJob < BaseJob
+    retry_on StandardError, wait: :polynomially_longer, attempts: 5 do |job, error|
+      SpreeSquare::WebhookEvent.find_by(id: job.arguments.first)&.mark_failed!(error)
+      SpreeSquare::Alerting.capture(error, context: 'order_webhook')
+    end
+
+    def perform(webhook_event_id)
+      event = SpreeSquare::WebhookEvent.find(webhook_event_id)
+
+      case event.event_type
+      when 'order.updated'
+        handle_order_updated(event.payload)
+      when 'order.fulfillment.updated'
+        handle_fulfillment_updated(event.payload)
+      end
+
+      event.mark_processed!
+    end
+
+    private
+
+    def handle_order_updated(payload)
+      data = payload.dig('data', 'object', 'order_updated') || {}
+      SpreeSquare::OrderStatusMapper.call(
+        square_order_id: data['order_id'],
+        version: data['version'],
+        order_state: data['state']
+      )
+    end
+
+    def handle_fulfillment_updated(payload)
+      data = payload.dig('data', 'object', 'order_fulfillment_updated') || {}
+      Array(data['fulfillment_update']).each do |update|
+        SpreeSquare::OrderStatusMapper.call(
+          square_order_id: data['order_id'],
+          version: data['version'],
+          fulfillment_state: update['new_state']
+        )
+      end
+    end
+  end
+end

data/app/jobs/spree_square/reconciliation_job.rb

@@ -0,0 +1,36 @@
+module SpreeSquare
+  # Nightly safety net for missed or failed webhooks — re-runs the same
+  # catalog import and inventory sync services M2/M3 already built (no new
+  # sync logic), just as a full pass instead of an incremental one. Cheap
+  # insurance for a restaurant-sized catalog; not built for a bulk catalog.
+  class ReconciliationJob < BaseJob
+    retry_on StandardError, wait: :polynomially_longer, attempts: 3 do |_job, error|
+        SpreeSquare::Alerting.capture(error, context: 'reconciliation')
+    end
+
+    def perform
+      SpreeSquare::CatalogImporter.call
+      reconcile_inventory
+    end
+
+    private
+
+    def reconcile_inventory
+      client = SpreeSquare::Client.instance
+      location_ids = SpreeSquare::LocationMapping.pluck(:square_location_id)
+      return if location_ids.empty?
+
+      # No `states:` filter — an item that went out of stock is exactly the
+      # kind of drift this job exists to catch, and it wouldn't show up in
+      # an IN_STOCK-only result.
+      client.inventory.batch_get_counts(location_ids: location_ids).each do |count|
+        SpreeSquare::InventorySync.call(
+          catalog_object_id: count.catalog_object_id,
+          location_id: count.location_id,
+          quantity: count.quantity,
+          state: count.state
+        )
+      end
+    end
+  end
+end

data/app/models/spree/line_item_decorator.rb

@@ -0,0 +1,55 @@
+module Spree
+  # Zeitwerk requires this module's name to match its file path exactly
+  # (app/models/spree/line_item_decorator.rb -> Spree::LineItemDecorator) —
+  # under dev's lazy autoloading, a mismatched name (e.g. a
+  # SpreeSquare-prefixed one) means nothing ever triggers loading this file
+  # at all, silently, since nothing references the name Zeitwerk expects.
+  module LineItemDecorator
+    # Transient carrier for selected modifier ids from add-to-cart through to
+    # SpreeSquare::Cart::AddItem, which reads it right after `super` to build
+    # the persistent LineItemModifier snapshot rows. Never persisted itself —
+    # `square_modifier_ids=` is populated via LineItem#options= (see
+    # `variant_decorator.rb`'s `square_modifier_ids_price_modifier_amount`,
+    # dispatched from the same options hash), which only lives for the
+    # request that created the line item.
+    attr_accessor :square_modifier_ids
+
+    # Both of these reset price to the variant's base price with no idea
+    # about our modifier selections (which live in a separate table
+    # specifically so a later Square catalog edit can't retroactively change
+    # what a customer already paid for) — necessary so a genuine price
+    # change from Square (M3) takes effect, but it means the modifier delta
+    # has to be re-added every time, not just once at add-to-cart.
+    #
+    # Confirmed (by grepping all of spree_core, not sampling) these are the
+    # *only* two places core reassigns line item price outside our own code:
+    # `recalculate_price` fires on cart mutations (Cart::AddItem calls it
+    # directly); `update_price` is what Order#update_line_item_prices! calls
+    # on every line item via a `before_transition from: :address` checkout
+    # callback — the bug that surfaced this: modifier pricing was correct
+    # right after add-to-cart, then silently reverted to base price the
+    # moment checkout address was submitted.
+    def recalculate_price
+      super
+      apply_square_modifier_delta!
+    end
+
+    def update_price
+      super
+      apply_square_modifier_delta!
+    end
+
+    private
+
+    def apply_square_modifier_delta!
+      return unless persisted?
+
+      delta_cents = SpreeSquare::LineItemModifier.where(line_item_id: id).sum(:price_cents_snapshot)
+      return if delta_cents.zero?
+
+      update_columns(price: price + (delta_cents / 100.0), updated_at: Time.current)
+    end
+  end
+
+  LineItem.prepend(LineItemDecorator)
+end

data/app/models/spree/variant_decorator.rb

@@ -0,0 +1,19 @@
+module Spree
+  # Zeitwerk-compliant name required for this file to autoload at all — see
+  # the comment in line_item_decorator.rb.
+  module VariantDecorator
+    # Hooks into Spree's own pluggable price-modifier dispatch
+    # (Variant#price_modifier_amount calls "#{key}_price_modifier_amount" for
+    # each key present in the line item's `options`) so the *initial*
+    # add-to-cart price is correct immediately, before LineItemModifier rows
+    # even exist yet. The decorated LineItem#recalculate_price is what keeps
+    # it correct after that.
+    def square_modifier_ids_price_modifier_amount(modifier_ids)
+      return 0 if modifier_ids.blank?
+
+      SpreeSquare::Modifier.where(square_modifier_id: Array(modifier_ids)).sum(:price_cents) / 100.0
+    end
+  end
+
+  Variant.prepend(VariantDecorator)
+end

data/app/models/spree_square/catalog_mapping.rb

@@ -0,0 +1,25 @@
+module SpreeSquare
+  # Maps a Square catalog object (ITEM or ITEM_VARIATION) to the Spree record
+  # it was imported into. `square_version` is Square's optimistic-concurrency
+  # token — compared before writing so out-of-order or duplicate webhook
+  # delivery (M3) can't clobber newer data with older data.
+  class CatalogMapping < Spree.base_class
+    self.table_name = 'spree_square_catalog_mappings'
+
+    ITEM = 'item'.freeze
+    ITEM_VARIATION = 'item_variation'.freeze
+
+    belongs_to :product, class_name: 'Spree::Product', foreign_key: 'spree_product_id', optional: true
+    belongs_to :variant, class_name: 'Spree::Variant', foreign_key: 'spree_variant_id', optional: true
+
+    validates :square_catalog_object_id, presence: true, uniqueness: true
+    validates :square_object_type, presence: true, inclusion: { in: [ITEM, ITEM_VARIATION] }
+
+    # True if `incoming_version` is not newer than what we already recorded —
+    # i.e. it's safe to skip re-processing (duplicate or out-of-order
+    # delivery).
+    def stale?(incoming_version)
+      square_version.present? && incoming_version.present? && incoming_version <= square_version
+    end
+  end
+end

data/app/models/spree_square/credential.rb

@@ -0,0 +1,41 @@
+module SpreeSquare
+  # A Square OAuth connection for one Spree::Store. Replaces the
+  # SQUARE_ACCESS_TOKEN env var with a per-store, self-service "Connect to
+  # Square" flow (see SpreeSquare::OauthClient and
+  # Spree::Admin::SquareOauthController) — the access-token mechanism Square
+  # requires multi-merchant apps to move away from before listing on the App
+  # Marketplace (personal access tokens are explicitly disallowed there).
+  #
+  # `access_token`/`refresh_token` are encrypted at rest (ActiveRecord::
+  # Encryption — see config/initializers/active_record_encryption.rb); Square
+  # tokens expire every 30 days and Square recommends refreshing every 7 or
+  # fewer, hence REFRESH_BUFFER below.
+  class Credential < Spree.base_class
+    self.table_name = 'spree_square_credentials'
+
+    REFRESH_BUFFER = 7.days
+
+    belongs_to :store, class_name: 'Spree::Store'
+
+    encrypts :access_token, :refresh_token
+
+    validates :store, presence: true, uniqueness: true
+    validates :square_merchant_id, presence: true, uniqueness: true
+
+    def sandbox?
+      square_environment == 'sandbox'
+    end
+
+    def expired?
+      expires_at.present? && expires_at <= Time.current
+    end
+
+    # True once we're inside Square's recommended refresh window — checked
+    # before every API call (see SpreeSquare::Client#ensure_fresh!) rather
+    # than on a schedule, so a credential that's gone briefly unused still
+    # gets refreshed the moment it's needed again.
+    def needs_refresh?
+      expires_at.present? && expires_at <= REFRESH_BUFFER.from_now
+    end
+  end
+end

data/app/models/spree_square/line_item_modifier.rb

@@ -0,0 +1,24 @@
+module SpreeSquare
+  # A modifier selected on a specific line item, snapshotted at add-to-cart
+  # time. The snapshot (not a live reference) is deliberate: a later Square
+  # menu edit must never retroactively change what a past order shows or
+  # cost.
+  class LineItemModifier < Spree.base_class
+    self.table_name = 'spree_square_line_item_modifiers'
+
+    belongs_to :line_item, class_name: 'Spree::LineItem'
+    belongs_to :modifier, class_name: 'SpreeSquare::Modifier', optional: true
+
+    validates :name_snapshot, presence: true
+    validates :price_cents_snapshot, numericality: true
+
+    def self.build_from(modifier)
+      new(
+        modifier: modifier,
+        square_modifier_id: modifier.square_modifier_id,
+        name_snapshot: modifier.name,
+        price_cents_snapshot: modifier.price_cents
+      )
+    end
+  end
+end

data/app/models/spree_square/location_mapping.rb

@@ -0,0 +1,14 @@
+module SpreeSquare
+  # Maps a Square Location 1:1 to a Spree::StockLocation. Restaurant branches
+  # map onto Spree's existing multi-warehouse StockLocation model —
+  # StockItem's per-location inventory tracking is exactly what "86'd at this
+  # branch but not that one" needs, for free.
+  class LocationMapping < Spree.base_class
+    self.table_name = 'spree_square_location_mappings'
+
+    belongs_to :stock_location, class_name: 'Spree::StockLocation', foreign_key: 'spree_stock_location_id'
+
+    validates :square_location_id, presence: true, uniqueness: true
+    validates :stock_location, presence: true
+  end
+end

data/app/models/spree_square/modifier.rb

@@ -0,0 +1,14 @@
+module SpreeSquare
+  # Mirrors a single Square MODIFIER (e.g. "Extra cheese", +$1.50).
+  class Modifier < Spree.base_class
+    self.table_name = 'spree_square_modifiers'
+
+    belongs_to :modifier_list, class_name: 'SpreeSquare::ModifierList'
+
+    validates :square_modifier_id, presence: true, uniqueness: true
+    validates :name, presence: true
+    validates :price_cents, numericality: { greater_than_or_equal_to: 0 }
+
+    def price = price_cents / 100.0
+  end
+end

data/app/models/spree_square/modifier_list.rb

@@ -0,0 +1,23 @@
+module SpreeSquare
+  # Mirrors a Square MODIFIER_LIST (e.g. "Choose your sauce"). Modeled
+  # separately from Spree's OptionType/Variant system on purpose — Square
+  # modifiers are multi-select, per-line-item customizations, not mutually
+  # exclusive product variations, and forcing them through OptionType would
+  # explode the variant matrix combinatorially.
+  class ModifierList < Spree.base_class
+    self.table_name = 'spree_square_modifier_lists'
+
+    SINGLE = 'SINGLE'.freeze
+    MULTIPLE = 'MULTIPLE'.freeze
+
+    has_many :modifiers, class_name: 'SpreeSquare::Modifier', dependent: :destroy
+    has_many :product_modifier_lists, class_name: 'SpreeSquare::ProductModifierList', dependent: :destroy
+    has_many :products, class_name: 'Spree::Product', through: :product_modifier_lists
+
+    validates :square_modifier_list_id, presence: true, uniqueness: true
+    validates :name, presence: true
+    validates :selection_type, inclusion: { in: [SINGLE, MULTIPLE] }
+
+    def multiple? = selection_type == MULTIPLE
+  end
+end

data/app/models/spree_square/order_mapping.rb

@@ -0,0 +1,15 @@
+module SpreeSquare
+  # Maps a Spree::Order to the Square Order (and its EXTERNAL payment) it was
+  # pushed to on completion.
+  class OrderMapping < Spree.base_class
+    self.table_name = 'spree_square_order_mappings'
+
+    belongs_to :order, class_name: 'Spree::Order', foreign_key: 'spree_order_id'
+
+    validates :order, presence: true, uniqueness: true
+
+    def mark_failed!(error)
+      update!(push_error: error.to_s.truncate(2000))
+    end
+  end
+end

data/app/models/spree_square/product_modifier_list.rb

@@ -0,0 +1,12 @@
+module SpreeSquare
+  # Join: which modifier lists apply to which product (a product can have
+  # several — e.g. "Choose your sauce" + "Extra toppings").
+  class ProductModifierList < Spree.base_class
+    self.table_name = 'spree_square_product_modifier_lists'
+
+    belongs_to :product, class_name: 'Spree::Product'
+    belongs_to :modifier_list, class_name: 'SpreeSquare::ModifierList'
+
+    validates :modifier_list_id, uniqueness: { scope: :product_id }
+  end
+end

data/app/models/spree_square/taxon_mapping.rb

@@ -0,0 +1,25 @@
+module SpreeSquare
+  # Maps a Square Category to a Spree::Category — the modern, store-scoped
+  # replacement for the legacy Taxonomy-backed Taxon system (see
+  # Spree::Category's own comment; it becomes the base class in Spree 6.0).
+  #
+  # Spree::Category isn't true STI (spree_taxons has no `type` column to
+  # dispatch on) — it's a plain Taxon subclass distinguished only by
+  # `default_scope { manual }` and an overridden `requires_taxonomy?`
+  # (false, vs. Taxon's own `true`). That means the association's
+  # `class_name` is what determines which class `#taxon` instantiates as,
+  # not the row's own data. Declaring it as `'Spree::Taxon'` here meant
+  # every re-fetched taxon silently reverted to the base class — Category's
+  # `requires_taxonomy?` override never applied, so any re-save (e.g. a
+  # name update from a later Square sync) failed with a bogus "Taxonomy
+  # can't be blank", even though the taxon was created as a Category with
+  # no taxonomy in the first place.
+  class TaxonMapping < Spree.base_class
+    self.table_name = 'spree_square_taxon_mappings'
+
+    belongs_to :taxon, class_name: 'Spree::Category', foreign_key: 'spree_taxon_id'
+
+    validates :square_category_id, presence: true, uniqueness: true
+    validates :taxon, presence: true
+  end
+end

data/app/models/spree_square/webhook_event.rb

@@ -0,0 +1,21 @@
+module SpreeSquare
+  # Idempotency + audit log for inbound Square webhook notifications. The
+  # unique index on square_event_id is what makes Square's at-least-once
+  # delivery safe to process without duplicating side effects.
+  class WebhookEvent < Spree.base_class
+    self.table_name = 'spree_square_webhook_events'
+
+    validates :square_event_id, presence: true, uniqueness: true
+    validates :event_type, presence: true
+
+    scope :pending, -> { where(status: 'pending') }
+
+    def mark_processed!
+      update!(status: 'processed', processed_at: Time.current)
+    end
+
+    def mark_failed!(error)
+      update!(status: 'failed', processed_at: Time.current, error_message: error.to_s.truncate(1000))
+    end
+  end
+end

data/app/serializers/spree_square/line_item_serializer.rb

@@ -0,0 +1,13 @@
+module SpreeSquare
+  # Exposes the modifiers selected on a line item (for cart/checkout
+  # display) using the snapshot recorded at add-to-cart time — never a live
+  # lookup, so a later Square menu edit can't change what's shown for an
+  # existing cart/order.
+  class LineItemSerializer < Spree::Api::V3::LineItemSerializer
+    attribute :square_modifiers do |line_item|
+      SpreeSquare::LineItemModifier.where(line_item_id: line_item.id).map do |lim|
+        { name: lim.name_snapshot, price_cents: lim.price_cents_snapshot, display_price: lim.price_cents_snapshot / 100.0 }
+      end
+    end
+  end
+end

data/app/serializers/spree_square/product_serializer.rb

@@ -0,0 +1,47 @@
+module SpreeSquare
+  # Adds the modifier lists attached to a product (see
+  # customization/api.mdx's documented pattern: subclass the core V3
+  # serializer and register via Spree::Api::Dependencies, rather than
+  # decorating Spree::Api::V3::ProductSerializer directly).
+  class ProductSerializer < Spree::Api::V3::ProductSerializer
+    # Re-declares the `categories` field from the core serializer (Alba
+    # associations are keyed by name, so redeclaring here overrides it) to
+    # fix a NoMethodError on `Spree::Category` taxons.
+    #
+    # The core field is `taxons.select { |t| t.taxonomy.store_id == ... }`,
+    # which assumes every taxon belongs to a Taxonomy. `Spree::Category` (see
+    # its own comment: the store-scoped, taxonomy-free replacement — becomes
+    # the base class in Spree 6.0) has `taxonomy_id: nil`, so `t.taxonomy` is
+    # nil and `.store_id` raises. Any `expand=categories` (or
+    # `categories.ancestors`, as the Next.js storefront's PDP always
+    # requests) 500s for every product in this catalog, since it's entirely
+    # Category-based. A Category is already store-scoped via its own
+    # `store_id` column (no taxonomy indirection needed), so that's the
+    # correct check to fall back to when `taxonomy` is nil.
+    many :taxons,
+         proc { |taxons, params|
+           taxons.select { |t| (t.taxonomy&.store_id || t.store_id) == params[:store].id }
+         },
+         key: :categories,
+         resource: proc { Spree.api.category_serializer },
+         if: proc { expand?('categories') }
+
+    attribute :modifier_lists do |product|
+      SpreeSquare::ProductModifierList.where(product_id: product.id)
+                                       .includes(modifier_list: :modifiers)
+                                       .map do |pml|
+        list = pml.modifier_list
+        {
+          id: list.square_modifier_list_id,
+          name: list.name,
+          selection_type: list.selection_type,
+          min_selected_modifiers: list.min_selected_modifiers,
+          max_selected_modifiers: list.max_selected_modifiers,
+          modifiers: list.modifiers.map do |m|
+            { id: m.square_modifier_id, name: m.name, price_cents: m.price_cents, display_price: m.price }
+          end
+        }
+      end
+    end
+  end
+end

data/app/services/spree_square/alerting.rb

@@ -0,0 +1,17 @@
+module SpreeSquare
+  # One place for "this needs a human" — used when a job exhausts its
+  # retries. Reports to Sentry (already in this app's stack) when available,
+  # always logs at error level regardless so nothing depends on Sentry being
+  # configured to at least be visible in the server log.
+  class Alerting
+    def self.capture(error, context: {})
+      context = { source: 'spree_square' }.merge(context.is_a?(String) ? { area: context } : context)
+
+      Rails.logger.error("[SpreeSquare] #{context[:area] || 'error'}: #{error.class}: #{error.message}")
+
+      return unless defined?(Sentry)
+
+      Sentry.capture_exception(error, extra: context)
+    end
+  end
+end

data/app/services/spree_square/cart/add_item.rb

@@ -0,0 +1,53 @@
+module SpreeSquare
+  module Cart
+    # Mirrors Spree::Cart::AddItem's own step sequence (see CLAUDE.md pattern
+    # #2 — swap the service, don't decorate it) with one inserted step.
+    #
+    # Selected modifier ids arrive via the line item's transient
+    # `square_modifier_ids` (set by LineItem#options=, populated from the
+    # `options:` param — see variant_decorator.rb's dispatch target and the
+    # `Spree::PermittedAttributes.line_item_attributes` addition in this
+    # extension's initializer). That gets the *initial* price right via
+    # Spree's own price-modifier mechanism, but the persistent
+    # LineItemModifier snapshot rows — what survives future recalculations
+    # and what M5's order push reads — don't exist until this step creates
+    # them. `add_to_line_item` already called `recalculate_price` once
+    # (before these rows existed, so it found no delta); calling it again
+    # here is what makes the response actually reflect the final price.
+    class AddItem < Spree::Cart::AddItem
+      # Spree::ServiceModule::Base is prepended onto the *parent* class
+      # (Spree::Cart::AddItem). A subclass's own `call` sits ahead of that
+      # prepended module in ITS OWN ancestor chain (subclassing doesn't lower
+      # the subclass's method priority below modules prepended only onto the
+      # ancestor) — without re-prepending here, `run` blows up on a nil
+      # `@_passed_input` because Base#call never got a chance to initialize it.
+      prepend Spree::ServiceModule::Base
+
+      def call(order:, variant:, quantity: nil, metadata: {}, public_metadata: {}, private_metadata: {}, options: {})
+        ApplicationRecord.transaction do
+          run :add_to_line_item
+          run :attach_square_modifiers
+          run :handle_stock_reservations
+          run Spree.cart_recalculate_service
+        end
+      end
+
+      private
+
+      def attach_square_modifiers(order:, line_item:, line_item_created:, options:)
+        modifier_ids = Array(line_item.square_modifier_ids)
+
+        if modifier_ids.present? && line_item_created
+          SpreeSquare::Modifier.where(square_modifier_id: modifier_ids).find_each do |modifier|
+            lim = SpreeSquare::LineItemModifier.build_from(modifier)
+            lim.line_item = line_item
+            lim.save!
+          end
+          line_item.recalculate_price
+        end
+
+        success(order: order, line_item: line_item, line_item_created: line_item_created, options: options)
+      end
+    end
+  end
+end

data/app/services/spree_square/catalog_importer.rb

@@ -0,0 +1,57 @@
+module SpreeSquare
+  # Full catalog import: pulls every ITEM + CATEGORY + MODIFIER_LIST from
+  # Square (with related objects — images, referenced categories — inlined
+  # via `include_related_objects`) and upserts them into Spree via
+  # CatalogObjectMapper. Categories and modifier lists are imported before
+  # items so an item can resolve its `category_id` / `modifier_list_info` to
+  # an already-mapped record.
+  class CatalogImporter
+    Result = Struct.new(:categories_count, :modifier_lists_count, :items_count, keyword_init: true)
+
+    def self.call = new.call
+
+    def call
+      client = SpreeSquare::Client.instance
+      objects, related_by_id = fetch_all(client)
+
+      by_type = objects.group_by(&:type)
+      categories = by_type.fetch('CATEGORY', [])
+      modifier_lists = by_type.fetch('MODIFIER_LIST', [])
+      items = by_type.fetch('ITEM', [])
+
+      mapper = CatalogObjectMapper.new(related_objects_by_id: related_by_id)
+      categories.each { |category| mapper.map_category(category) }
+      modifier_lists.each { |list| mapper.map_modifier_list(list) }
+      items.each { |item| mapper.map_item(item) }
+
+      Result.new(categories_count: categories.size, modifier_lists_count: modifier_lists.size, items_count: items.size)
+    end
+
+    private
+
+    # Square's search is a single page per call; loop on `cursor` until
+    # exhausted. Fine for a restaurant-sized catalog (dozens to low hundreds
+    # of items) — not built for bulk/enterprise catalogs.
+    def fetch_all(client)
+      objects = []
+      related_by_id = {}
+      cursor = nil
+
+      loop do
+        response = client.catalog.search(
+          object_types: %w[ITEM CATEGORY MODIFIER_LIST],
+          include_related_objects: true,
+          cursor: cursor
+        )
+
+        objects.concat(Array(response.objects))
+        Array(response.related_objects).each { |o| related_by_id[o.id] = o }
+
+        cursor = response.cursor
+        break if cursor.blank?
+      end
+
+      [objects, related_by_id]
+    end
+  end
+end