spree_square 0.1.0

data/app/services/spree_square/catalog_object_mapper.rb

@@ -0,0 +1,226 @@
+require 'open-uri'
+
+module SpreeSquare
+  # Maps single Square catalog objects (CATEGORY, ITEM, ITEM_VARIATION) onto
+  # Spree records. Square is the source of truth for the menu — this is a
+  # one-way mirror, never the reverse.
+  #
+  # `related_objects_by_id` is a lookup (built by CatalogImporter from a
+  # SearchCatalogObjects response's `related_objects`) used to resolve
+  # references like an item's `category_id` to the full CatalogObjectCategory,
+  # or an image id to its CatalogObjectImage.
+  class CatalogObjectMapper
+    # One shared OptionType for any item that has more than one variation
+    # (e.g. sizes). Single-variation items skip this entirely and use the
+    # product's master variant — avoids OptionType/OptionValue bookkeeping for
+    # the common case, since most menu items don't have real variations.
+    VARIATION_OPTION_TYPE_NAME = 'square_variation'.freeze
+
+    def initialize(related_objects_by_id: {})
+      @related_objects_by_id = related_objects_by_id
+      @store = Spree::Store.default
+      @shipping_category = Spree::ShippingCategory.find_by(name: 'Default') || Spree::ShippingCategory.first
+      @channel = Spree::Channel.find_by(code: 'online') || Spree::Channel.first
+    end
+
+    def map_category(square_object)
+      data = square_object.category_data
+      name = data.name.presence || 'Uncategorized'
+      mapping = SpreeSquare::TaxonMapping.find_or_initialize_by(square_category_id: square_object.id)
+
+      # Square's SearchCatalogObjects index is only eventually consistent —
+      # a category deleted and recreated (or, as observed in practice, a
+      # stale duplicate momentarily reappearing alongside the fresh one) can
+      # surface a second CatalogObject with a different id but the same
+      # name before a TaxonMapping exists for it. Category name+store is
+      # unique in Spree (see Spree::Category#requires_taxonomy? — no
+      # taxonomy, so uniqueness is scoped to store_id), so falling back to
+      # an existing same-named category avoids a hard crash on that race
+      # instead of trying (and failing) to create a duplicate.
+      taxon = mapping.taxon || Spree::Category.find_by(store: @store, name: name) || Spree::Category.new(store: @store)
+      taxon.name = name
+      taxon.save!
+
+      mapping.taxon = taxon
+      mapping.square_version = square_object.version
+      mapping.save!
+
+      taxon
+    end
+
+    # A Square MODIFIER_LIST embeds its full MODIFIER objects inline (same
+    # pattern as ITEM#variations) — no follow-up API call needed.
+    def map_modifier_list(square_object)
+      data = square_object.modifier_list_data
+      list = SpreeSquare::ModifierList.find_or_initialize_by(square_modifier_list_id: square_object.id)
+      list.name = data.name.presence || 'Options'
+      list.selection_type = data.selection_type.presence || SpreeSquare::ModifierList::SINGLE
+      list.min_selected_modifiers = data.min_selected_modifiers
+      list.max_selected_modifiers = data.max_selected_modifiers
+      list.square_version = square_object.version
+      list.save!
+
+      Array(data.modifiers).each { |modifier| map_modifier(modifier, list) }
+      list
+    end
+
+    def map_modifier(square_object, modifier_list)
+      data = square_object.modifier_data
+      modifier = SpreeSquare::Modifier.find_or_initialize_by(square_modifier_id: square_object.id)
+      modifier.modifier_list = modifier_list
+      modifier.name = data.name.presence || 'Option'
+      modifier.price_cents = data.price_money&.amount || 0
+      modifier.square_version = square_object.version
+      modifier.save!
+      modifier
+    end
+
+    def map_item(square_object)
+      data = square_object.item_data
+      mapping = SpreeSquare::CatalogMapping.find_or_initialize_by(
+        square_catalog_object_id: square_object.id,
+        square_object_type: SpreeSquare::CatalogMapping::ITEM
+      )
+      return mapping.product if mapping.persisted? && mapping.stale?(square_object.version)
+
+      product = mapping.product || Spree::Product.new(
+        store: @store,
+        shipping_category: @shipping_category,
+        status: 'active',
+        slug: generate_slug(data.name, square_object.id)
+      )
+      product.name = data.name.presence || 'Untitled item'
+      product.description = data.description
+      product.save!
+
+      publish!(product)
+      assign_taxons!(product, data)
+      assign_modifier_lists!(product, data)
+
+      mapping.product = product
+      mapping.square_version = square_object.version
+      mapping.last_synced_at = Time.current
+      mapping.save!
+
+      Array(data.variations).each { |variation| map_variation(variation, product) }
+      import_primary_image(product, data.image_ids&.first) if product.images.empty?
+
+      revalidate!(product)
+      product
+    end
+
+    def map_variation(square_object, product)
+      data = square_object.item_variation_data
+      mapping = SpreeSquare::CatalogMapping.find_or_initialize_by(
+        square_catalog_object_id: square_object.id,
+        square_object_type: SpreeSquare::CatalogMapping::ITEM_VARIATION
+      )
+      return mapping.variant if mapping.persisted? && mapping.stale?(square_object.version)
+
+      variant = mapping.variant || pick_variant(product, data)
+      variant.sku = square_object.id if variant.sku.blank?
+      variant.save!
+
+      amount = (data.price_money&.amount || 0) / 100.0
+      variant.set_price(data.price_money&.currency || @store.default_currency, amount)
+
+      mapping.variant = variant
+      mapping.square_version = square_object.version
+      mapping.last_synced_at = Time.current
+      mapping.save!
+
+      # A variation's own price/sku change touches the product without
+      # firing Spree's product.updated event (see Revalidator) — the
+      # storefront's product cache needs telling explicitly either way.
+      revalidate!(product)
+      variant
+    end
+
+    private
+
+    def revalidate!(product)
+      SpreeSquare::Revalidator.call(['products', "product:#{product.slug}"])
+    end
+
+    # The first variation ever imported for a product reuses its master
+    # variant (detected by the master not having a SKU yet — we always set one
+    # from the Square variation id). Only the second-and-later variations
+    # force creating real (non-master) variants with an option value
+    # distinguishing them — Spree requires at least one option value on any
+    # non-master variant.
+    def pick_variant(product, data)
+      return product.master if product.master.sku.blank?
+
+      option_value = find_or_create_option_value(data.name.presence || 'Default')
+      variant = product.variants.build
+      variant.option_values << option_value
+      variant
+    end
+
+    def find_or_create_option_value(name)
+      option_type = Spree::OptionType.find_or_create_by!(name: VARIATION_OPTION_TYPE_NAME) do |ot|
+        ot.presentation = 'Variation'
+      end
+      option_type.option_values.find_or_create_by!(name: name.parameterize) do |ov|
+        ov.presentation = name
+      end
+    end
+
+    def publish!(product)
+      return unless @channel
+
+      product.product_publications.find_or_create_by!(channel: @channel)
+    end
+
+    def assign_taxons!(product, item_data)
+      category_ids = Array(item_data.category_id) + Array(item_data.categories).map(&:id)
+      taxons = category_ids.uniq.filter_map do |square_category_id|
+        SpreeSquare::TaxonMapping.find_by(square_category_id: square_category_id)&.taxon
+      end
+      product.taxons = taxons if taxons.any?
+    end
+
+    # Square is master: replace the full set each sync so a modifier list
+    # detached from an item in Square disappears here too, not just
+    # additions.
+    def assign_modifier_lists!(product, item_data)
+      list_ids = Array(item_data.modifier_list_info)
+                 .reject { |info| info.enabled == false }
+                 .map(&:modifier_list_id)
+
+      lists = SpreeSquare::ModifierList.where(square_modifier_list_id: list_ids)
+      existing_ids = SpreeSquare::ProductModifierList.where(product_id: product.id).pluck(:modifier_list_id)
+
+      (lists.pluck(:id) - existing_ids).each do |list_id|
+        SpreeSquare::ProductModifierList.create!(product: product, modifier_list_id: list_id)
+      end
+      (existing_ids - lists.pluck(:id)).each do |list_id|
+        SpreeSquare::ProductModifierList.where(product_id: product.id, modifier_list_id: list_id).destroy_all
+      end
+    end
+
+    def import_primary_image(product, image_id)
+      return if image_id.blank?
+
+      image_object = @related_objects_by_id[image_id]
+      url = image_object&.image_data&.url
+      return if url.blank?
+
+      downloaded = URI.parse(url).open
+      image = product.master.images.build
+      image.attachment.attach(
+        io: downloaded,
+        filename: "#{product.slug}#{File.extname(URI.parse(url).path.to_s).presence || '.jpg'}",
+        content_type: downloaded.content_type
+      )
+      image.save!
+    rescue StandardError => e
+      Rails.logger.warn("[SpreeSquare] image import failed for product #{product.id}: #{e.message}")
+    end
+
+    def generate_slug(name, square_id)
+      base = name.presence || 'item'
+      "#{base.parameterize}-#{square_id.downcase}"
+    end
+  end
+end

data/app/services/spree_square/client.rb

@@ -0,0 +1,116 @@
+# Bundler's gem-name-based auto-require doesn't resolve "square.rb" -> "square"
+# (the gem's require path), so it's not auto-required by Bundler.require.
+require 'square'
+
+module SpreeSquare
+  # Thin wrapper around Square::Client (the current, Fern-generated SDK —
+  # `square.rb` v46+). All Square API access in this extension goes through
+  # here so credential lookup and environment selection live in one place.
+  #
+  # Deliberately NOT using square_legacy's client.orders_api.create_order-style
+  # API that most tutorials still show — that's the old SDK shape bundled
+  # alongside the new one for migration purposes only.
+  #
+  # Credential resolution, in order:
+  #   1. A SpreeSquare::Credential for the given store (self-service "Connect
+  #      to Square" via OAuth — see SpreeSquare::OauthClient) — refreshed
+  #      first if it's inside Square's recommended renewal window.
+  #   2. SQUARE_ACCESS_TOKEN from ENV — the original single-tenant path, kept
+  #      so existing sandbox/dev setups (and anyone not yet using OAuth)
+  #      don't break. Square disallows this path for real multi-merchant use
+  #      ("partner developers must not request nor use personal access
+  #      tokens from the sellers who use their application") — it's a dev
+  #      convenience here, not the production story.
+  class Client
+    class MissingCredentialsError < StandardError; end
+
+    # Deliberately NOT memoized: this used to be `@instance ||= new`, but
+    # once a store can connect via OAuth mid-process (an admin clicking
+    # "Connect to Square" while Puma/Solid Queue keep running), caching the
+    # first resolution forever means every job in that process would keep
+    # using the stale pre-connection state until a restart. The lookup this
+    # re-does each call is one indexed `SpreeSquare::Credential` query — not
+    # worth trading correctness for.
+    def self.instance
+      for_store
+    end
+
+    def self.for_store(store = Spree::Store.default)
+      new(credential: SpreeSquare::Credential.find_by(store: store))
+    end
+
+    def initialize(credential: nil)
+      @credential = credential
+      token = resolve_token
+      raise MissingCredentialsError, 'No Square credential connected and SQUARE_ACCESS_TOKEN is not set' if token.blank?
+
+      @client = Square::Client.new(base_url: base_url, token: token)
+    end
+
+    def catalog = @client.catalog
+    def orders = @client.orders
+    def payments = @client.payments
+    def inventory = @client.inventory
+    def locations = @client.locations
+    def webhooks = @client.webhooks
+
+    def location_id
+      fetch(:location_id, env_key: 'SQUARE_LOCATION_ID')
+    end
+
+    # App-level, not per-merchant: one webhook subscription/signing key
+    # covers every store this deployment serves, same whether a given store
+    # authenticates via OAuth or the ENV fallback above.
+    def webhook_signature_key
+      fetch(:webhook_signature_key, env_key: 'SQUARE_WEBHOOK_SIGNATURE_KEY')
+    end
+
+    def sandbox?
+      environment == 'sandbox'
+    end
+
+    private
+
+    def resolve_token
+      return fetch(:access_token, env_key: 'SQUARE_ACCESS_TOKEN') unless @credential
+
+      refresh_if_needed!
+      @credential.access_token
+    end
+
+    def refresh_if_needed!
+      return unless @credential.needs_refresh?
+
+      response = SpreeSquare::OauthClient.refresh(@credential)
+      @credential.update!(
+        access_token: response.access_token,
+        refresh_token: response.refresh_token,
+        expires_at: Time.iso8601(response.expires_at),
+        refresh_token_expires_at: response.refresh_token_expires_at.present? ? Time.iso8601(response.refresh_token_expires_at) : nil
+      )
+    rescue StandardError => e
+      # A failed refresh shouldn't crash whatever sync job triggered this
+      # client lookup — fall through and try the existing (possibly
+      # still-valid, or about to 401) access_token rather than raising here.
+      # The eventual 401 from Square is a clearer signal than this method
+      # raising somewhere deep inside a webhook job.
+      Rails.logger.error("[SpreeSquare] token refresh failed for store #{@credential.store_id}: #{e.message}")
+    end
+
+    def base_url
+      sandbox? ? Square::Environment::SANDBOX : Square::Environment::PRODUCTION
+    end
+
+    def environment
+      @credential&.square_environment || ENV.fetch('SQUARE_ENVIRONMENT', 'sandbox')
+    end
+
+    # Rails credentials first (config/credentials.yml.enc, scoped by
+    # environment: production.yml.enc vs sandbox stays in the base file for
+    # dev), falling back to plain ENV for 12-factor deployments (Heroku,
+    # Render, Fly, and — today — our own .env-driven Docker Compose setup).
+    def fetch(key, env_key:)
+      Rails.application.credentials.dig(:square, environment.to_sym, key) || ENV[env_key].presence
+    end
+  end
+end

data/app/services/spree_square/find_line_item_by_variant.rb

@@ -0,0 +1,21 @@
+module SpreeSquare
+  # Spree::LineItems::FindByVariant matches purely on variant_id — it calls
+  # Spree.cart_compare_line_items_service but discards the result without
+  # using it to gate anything, so customizing that comparator alone has no
+  # effect (verified directly: swapping just the comparator did not stop two
+  # differently-modified line items from merging). This finder replaces the
+  # matching logic itself, so "Margherita Pizza + extra cheese" and
+  # "Margherita Pizza + no cheese" land in separate line items instead of
+  # silently merging into one with the first selection's modifiers.
+  class FindLineItemByVariant
+    def execute(order:, variant:, options: {})
+      requested = Array(options[:square_modifier_ids] || options['square_modifier_ids']).sort
+
+      order.line_items.where(variant_id: variant.id).detect do |line_item|
+        existing = SpreeSquare::LineItemModifier.where(line_item_id: line_item.id)
+                                                 .pluck(:square_modifier_id).compact.sort
+        existing == requested
+      end
+    end
+  end
+end

data/app/services/spree_square/inventory_sync.rb

@@ -0,0 +1,29 @@
+module SpreeSquare
+  # Applies a single Square inventory count to the matching Spree::StockItem.
+  # No backordering food: backorderable is always forced false regardless of
+  # what it was set to before.
+  class InventorySync
+    def self.call(...) = new.call(...)
+
+    def call(catalog_object_id:, location_id:, quantity:, state: 'IN_STOCK')
+      mapping = SpreeSquare::CatalogMapping.find_by(
+        square_catalog_object_id: catalog_object_id,
+        square_object_type: SpreeSquare::CatalogMapping::ITEM_VARIATION
+      )
+      return unless mapping&.variant
+
+      location_mapping = SpreeSquare::LocationMapping.find_by(square_location_id: location_id)
+      return unless location_mapping
+
+      stock_item = location_mapping.stock_location.stock_item_or_create(mapping.variant)
+      stock_item.backorderable = false
+      stock_item.set_count_on_hand(state == 'IN_STOCK' ? quantity.to_i : 0)
+
+      # Stock changes touch product without firing product.updated (see
+      # Revalidator) — the storefront's "in stock"/"add to cart" state needs
+      # telling explicitly.
+      product = mapping.variant.product
+      SpreeSquare::Revalidator.call(['products', "product:#{product.slug}"])
+    end
+  end
+end

data/app/services/spree_square/oauth_client.rb

@@ -0,0 +1,116 @@
+# Bundler's gem-name-based auto-require doesn't resolve "square.rb" -> "square"
+# (the gem's require path), so it's not auto-required by Bundler.require —
+# see SpreeSquare::Client for the same note.
+require 'square'
+require 'net/http'
+
+module SpreeSquare
+  # The OAuth half of talking to Square — separate from SpreeSquare::Client
+  # (which makes authenticated Catalog/Orders/Payments calls with a token
+  # already in hand). This class is how that token gets obtained, refreshed,
+  # and revoked in the first place.
+  #
+  # Scopes requested cover every API spree_square actually calls elsewhere
+  # (Client#catalog/orders/payments/inventory/locations/webhooks) — keep this
+  # list in sync if a new Square API surface gets used.
+  class OauthClient
+    class ConfigurationError < StandardError; end
+
+    SCOPES = %w[
+      MERCHANT_PROFILE_READ
+      ITEMS_READ
+      INVENTORY_READ
+      INVENTORY_WRITE
+      ORDERS_READ
+      ORDERS_WRITE
+      PAYMENTS_WRITE
+    ].freeze
+
+    def self.authorize_url(...) = new.authorize_url(...)
+    def self.exchange_code(...) = new.exchange_code(...)
+    def self.refresh(...) = new.refresh(...)
+    def self.revoke(...) = new.revoke(...)
+
+    def initialize
+      @application_id = ENV['SQUARE_APPLICATION_ID'].presence
+      @application_secret = ENV['SQUARE_APPLICATION_SECRET'].presence
+      raise ConfigurationError, 'SQUARE_APPLICATION_ID is not set' if @application_id.blank?
+      raise ConfigurationError, 'SQUARE_APPLICATION_SECRET is not set' if @application_secret.blank?
+    end
+
+    # The URL to send the merchant's browser to. `session: false` forces
+    # Square to show its account chooser even if the browser is already
+    # signed in to a Square account — without it, a staff member testing
+    # this on a shared machine could silently connect the wrong account.
+    def authorize_url(redirect_uri:, state:)
+      params = {
+        client_id: @application_id,
+        scope: SCOPES.join(' '),
+        session: false,
+        state: state,
+        redirect_uri: redirect_uri
+      }
+      "#{base_url}/oauth2/authorize?#{params.to_query}"
+    end
+
+    def exchange_code(code:, redirect_uri:)
+      oauth_api.obtain_token(
+        client_id: @application_id,
+        client_secret: @application_secret,
+        code: code,
+        grant_type: 'authorization_code',
+        redirect_uri: redirect_uri
+      )
+    end
+
+    # Code-flow refresh (vs. PKCE) returns the *same* refresh token back —
+    # Square's docs call this out explicitly, so callers should always save
+    # whatever comes back here rather than assuming the old one still works.
+    def refresh(credential)
+      oauth_api.obtain_token(
+        client_id: @application_id,
+        client_secret: @application_secret,
+        refresh_token: credential.refresh_token,
+        grant_type: 'refresh_token'
+      )
+    end
+
+    # Square's RevokeToken endpoint doesn't use the normal `Bearer <token>`
+    # scheme every other call in this extension uses — it requires
+    # `Authorization: Client <application_secret>` instead, which the SDK's
+    # Square::Client can't produce (its Authorization header is fixed to
+    # Bearer at construction). Raw HTTP here, deliberately not routed
+    # through the SDK.
+    def revoke(credential)
+      uri = URI("#{base_url}/oauth2/revoke")
+      request = Net::HTTP::Post.new(uri)
+      request['Content-Type'] = 'application/json'
+      request['Authorization'] = "Client #{@application_secret}"
+      request.body = { client_id: @application_id, access_token: credential.access_token }.to_json
+
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
+      return if response.is_a?(Net::HTTPSuccess)
+
+      raise Square::Errors::ResponseError.subclass_for_code(response.code.to_i).new(response.body, code: response.code.to_i)
+    end
+
+    private
+
+    # A bearer token isn't needed for any of oauth2/authorize, oauth2/token,
+    # or oauth2/revoke (the latter uses the Client-secret scheme above
+    # instead) — passing `token: nil` here just produces an unused,
+    # harmless `Authorization: Bearer ` header on the token-exchange/refresh
+    # calls, which those endpoints ignore.
+    def oauth_api
+      @oauth_api ||= Square::Client.new(base_url: base_url, token: nil).o_auth
+    end
+
+    def base_url
+      sandbox? ? Square::Environment::SANDBOX : Square::Environment::PRODUCTION
+    end
+
+    def sandbox?
+      ENV.fetch('SQUARE_ENVIRONMENT', 'sandbox') == 'sandbox'
+    end
+  end
+end

data/app/services/spree_square/order_builder.rb

@@ -0,0 +1,79 @@
+module SpreeSquare
+  # Builds the Square CreateOrder payload for a completed Spree::Order.
+  # Deliberately omits pricing beyond per-line-item base_price_money/modifiers
+  # — no taxes/discounts sent — so Square's computed total_money is exactly
+  # what OrderPusher then charges via the EXTERNAL payment, with nothing for
+  # Square's own tax/discount engine to add on top and create a mismatch.
+  class OrderBuilder
+    def self.call(...) = new.call(...)
+
+    def call(order)
+      location_mapping = location_mapping_for(order)
+      raise "No Square location mapped for order #{order.number}" unless location_mapping
+
+      {
+        location_id: location_mapping.square_location_id,
+        reference_id: order.number,
+        line_items: order.line_items.map { |line_item| build_line_item(line_item) },
+        fulfillments: [build_fulfillment(order)]
+      }
+    end
+
+    private
+
+    # Without a fulfillment, the order has nothing for the kitchen/POS to
+    # advance through — it just sits there as a paid ticket with no
+    # PROPOSED -> RESERVED -> PREPARED -> COMPLETED progression, and
+    # order.fulfillment.updated never fires (confirmed: a pushed order with
+    # no fulfillments produced zero fulfillment webhooks). PICKUP for now —
+    # "Pay at pickup" is the only payment method configured; DELIVERY comes
+    # with DoorDash Drive in phase 2.
+    def build_fulfillment(order)
+      {
+        type: 'PICKUP',
+        pickup_details: {
+          recipient: {
+            display_name: order.bill_address&.full_name || order.email,
+            email_address: order.email,
+            phone_number: order.bill_address&.phone
+          }.compact,
+          schedule_type: 'ASAP'
+        }
+      }
+    end
+
+    def location_mapping_for(order)
+      stock_location = order.shipments.first&.stock_location || Spree::StockLocation.find_by(default: true)
+      return nil unless stock_location
+
+      SpreeSquare::LocationMapping.find_by(spree_stock_location_id: stock_location.id)
+    end
+
+    def build_line_item(line_item)
+      currency = (line_item.currency || 'USD').upcase
+      catalog_mapping = SpreeSquare::CatalogMapping.find_by(
+        spree_variant_id: line_item.variant_id,
+        square_object_type: SpreeSquare::CatalogMapping::ITEM_VARIATION
+      )
+      modifiers = SpreeSquare::LineItemModifier.where(line_item_id: line_item.id).to_a
+      modifier_total_cents = modifiers.sum(&:price_cents_snapshot)
+      base_price_cents = (line_item.price * 100).round - modifier_total_cents
+
+      {
+        quantity: line_item.quantity.to_s,
+        name: line_item.name,
+        catalog_object_id: catalog_mapping&.square_catalog_object_id,
+        base_price_money: { amount: base_price_cents, currency: currency },
+        modifiers: modifiers.map { |modifier| build_modifier(modifier, currency) }
+      }.compact
+    end
+
+    def build_modifier(modifier, currency)
+      {
+        catalog_object_id: modifier.square_modifier_id,
+        name: modifier.name_snapshot,
+        base_price_money: { amount: modifier.price_cents_snapshot, currency: currency }
+      }
+    end
+  end
+end

data/app/services/spree_square/order_pusher.rb

@@ -0,0 +1,68 @@
+module SpreeSquare
+  # Pushes a completed Spree order into Square as a paid ticket: creates the
+  # Square Order, then records the payment Spree already collected as an
+  # EXTERNAL payment against it (Square's own first-class mechanism for
+  # "paid somewhere else" — its docs use exactly this "food delivery
+  # service" scenario as the example). No Square payment gateway needed for
+  # this to work.
+  #
+  # Charges exactly what Square computed as the order's own total_money,
+  # read back from the create-order response, rather than recomputing a
+  # total independently — guarantees the payment can never mismatch the
+  # order it's attached to.
+  class OrderPusher
+    def self.call(...) = new.call(...)
+
+    def call(order)
+      client = SpreeSquare::Client.instance
+      mapping = SpreeSquare::OrderMapping.find_or_initialize_by(order: order)
+
+      square_order = create_order(client, order)
+      mapping.update!(
+        square_order_id: square_order.id,
+        square_location_id: square_order.location_id,
+        square_version: square_order.version,
+        last_status: square_order.state
+      )
+
+      payment = record_external_payment(client, order, square_order)
+
+      # Attaching a fully-covering payment can advance Square's own order
+      # state immediately (e.g. OPEN -> COMPLETED) — re-fetch so the mapping
+      # reflects that instead of the pre-payment snapshot. M6 keeps this
+      # correct going forward via order.updated webhooks; this just avoids a
+      # misleading stale status in the window before the first one arrives.
+      refreshed = client.orders.get(order_id: square_order.id).order
+      mapping.update!(
+        square_payment_id: payment.id,
+        square_version: refreshed.version,
+        last_status: refreshed.state
+      )
+
+      mapping
+    end
+
+    private
+
+    def create_order(client, order)
+      payload = SpreeSquare::OrderBuilder.call(order)
+      response = client.orders.create(
+        idempotency_key: "spree-order-#{order.number}",
+        order: payload
+      )
+      response.order
+    end
+
+    def record_external_payment(client, order, square_order)
+      total = square_order.total_money
+      response = client.payments.create(
+        source_id: 'EXTERNAL',
+        idempotency_key: "spree-payment-#{order.number}",
+        amount_money: { amount: total.amount, currency: total.currency },
+        order_id: square_order.id,
+        external_details: { type: 'OTHER', source: 'Spree checkout' }
+      )
+      response.payment
+    end
+  end
+end