spree_square 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 199628697d1e2ef689462c4e4895ec7a90a271e5663cb3de8777533b15cdee50
-  data.tar.gz: 4d0137620c684345e4c4fa32bc8b75381d45e4992f773174a60ea0009ab4d55b
+  metadata.gz: de9d79909bb37dc35374d1b512f5e015f2e29f37b6aafe9948ee9cc5eb870c2a
+  data.tar.gz: aa8065c6c9c5fd613f97f1fcf5ba827bb5a4f6083dfd1259ed723b0214fe40ef
 SHA512:
-  metadata.gz: 96d1f3c46e20844a731be1d12a1616b2cd9f06d1be0160122615f491b5fc40ce6a0e865cb14eeb373c93b1c1e3f5e8fa460d0933c978f93fcc380d53576aabc7
-  data.tar.gz: 072bdfa3d7dee63493118d655ffaaa3df3e55cf9dc4dcddf39b6cb006057ef52218a2851f6444a2ea461de5bcaab3ef8c82edc36e8a589501ffa20defbe592df
+  metadata.gz: 6eab08d920ac2cee2dd52da0d728294733393b4b7c2f48ebe3c4f38f7a1b5f9f8e469569125d7843b58e38f6ea097aba71937da4f88a854fc1ec7a2c043b75a5
+  data.tar.gz: f56a193327ddf7ed32f34cfd31e1a47ca2f5a3d91506797d9278bcb0acfdb7f3fa5e1cb1a3889aa63a1baa1877cd151e6b15249cfb959a88b287003d141db21f

data/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to this project are documented here.
 
+## 0.2.0
+
+- **Sales tax, sourced from Square's own catalog tax config.** Square's Catalog API has no concept
+  of jurisdiction, so this is two pieces working together: a new rake task
+  (`spree_square:ensure_tax_zone`) sets up a Spree::Zone matching the store's own StockLocation
+  state (re-derived live, not hardcoded), and the catalog importer now pulls Square's `TAX`
+  catalog objects (`CatalogImporter`/`CatalogObjectMapper#map_tax`) plus each item's `tax_ids`
+  (`#resolve_tax_category`), mirroring them into `Spree::TaxRate`/`Spree::TaxCategory` — Spree's
+  own built-in tax-calculation engine does the actual per-order math, unchanged. An item carrying
+  more than one Square tax at once gets its own composite `Spree::TaxCategory` with one
+  `Spree::TaxRate` per constituent tax (`SpreeSquare::TaxMapping`/`TaxCategoryMapping`), rather
+  than forcing a single flat rate — correct for the general case, though this project's own
+  catalog only ever needs one. Disabling a tax in Square soft-deletes every `Spree::TaxRate` it
+  backs; re-enabling restores them. Reuses the existing `catalog.version.updated` webhook — no new
+  subscription needed.
+- New rake task `spree_square:setup_demo_tax` — creates a real "Sales Tax" object in Square
+  Sandbox, batch-attaches it to every item via `update_item_taxes`, and (Spree-side, since Square
+  has no concept of a delivery fee at all) applies the same tax category to every shipping method.
+- New read-only admin page, "Square Tax Rates" (`/admin/square_tax_rates`), mirroring the existing
+  Square Orders/Webhooks pages.
+- Fixed a real bug found while building this: `Spree::TaxRate`'s `has_one :calculator, dependent:
+  destroy` performs a REAL (hard) destroy even when the owning TaxRate is only soft-deleted —
+  acts_as_paranoid only intercepts the TaxRate's own row, not its dependent-destroy callback
+  chain. Re-enabling a previously-disabled tax rebuilds the lost calculator explicitly; without
+  this, the very next order recalculation against that rate raised
+  (`Spree::TaxRate#calculator` was blank).
+- Documented, not fixed here (pre-existing, discovered during manual verification): a store's
+  connected OAuth credential (`SpreeSquare::Credential`) may not carry `ITEMS_WRITE` if it was
+  authorized before this or `seed_demo_menu`'s scope needs existed — both item-write rake tasks
+  need it. Reconnecting via the admin's OAuth flow picks up the current scope list; until then,
+  `setup_demo_tax` explicitly bypasses the connected credential in favor of `SQUARE_ACCESS_TOKEN`.
+
+## 0.1.3
+
+- New demo menu content: a "Pizzas" category with 5 standalone pizzas plus a
+  Build-Your-Own Half & Half Pizza (two stacked SINGLE-select modifier lists,
+  "Left Half"/"Right Half", sharing the same 5 toppings) — the concrete
+  real-world case for two independent modifier lists stacked on one item.
+  Also 2 new combo items (Burger Combo, Family Feast Combo), joining the
+  existing Lunch Combo. Demo menu is now 45 items across 8 categories (up
+  from 37/7).
+
 ## 0.1.2
 
 - Two new demo menu items (a build-your-own bowl with stacked modifier lists, a combo meal with

data/README.md

@@ -70,6 +70,32 @@ The original single-tenant path: generate a token yourself from the Developer Da
 store that hasn't connected via OAuth — convenient for local development, but not something
 Square allows for real multi-merchant production use.
 
+## Sales tax
+
+Tax rates are configured in Square (the same place you manage the menu), not in Spree's admin —
+this extension keeps `Spree::TaxRate`/`Spree::TaxCategory` in sync with whatever `TAX` catalog
+objects and item `tax_ids` you set up in Square. **Square's Catalog API has no concept of
+jurisdiction**, so one one-time Spree-side step is still required:
+
+```bash
+bin/rails spree_square:ensure_tax_zone
+```
+
+This creates a `Spree::Zone` matching your store's own `Spree::StockLocation` state (re-derived
+live — re-run it if that address ever changes). From there, create a `TAX` object in Square and
+attach it to your taxable items (via the Square dashboard, or the Catalog API's
+`update_item_taxes`) — the next catalog sync (webhook or `spree_square:import_catalog`) picks it
+up automatically. `spree_square:setup_demo_tax` does both of the Square-side steps for you against
+a fresh Sandbox catalog, for a working demo without leaving the terminal.
+
+Delivery/shipping fees are entirely outside Square's model — assign a `tax_category` to your
+`Spree::ShippingMethod` records directly (`setup_demo_tax` does this too) if you want them taxed
+the same way.
+
+An item carrying more than one Square tax at once (rare — most stores have exactly one) gets its
+own composite `Spree::TaxCategory` combining all of them; Spree's own tax-calculation engine sums
+every rate that shares an item's category, so no special handling is needed at checkout time.
+
 ## Developing
 
 1. Create a dummy app

data/app/controllers/spree/admin/square_tax_rates_controller.rb

@@ -0,0 +1,28 @@
+module Spree
+  module Admin
+    # Read-only support/diagnostic view — no create/edit/destroy, this is
+    # visibility into what Square's own tax config has synced into Spree,
+    # not a place to change it (edits happen in Square's own dashboard).
+    # Mirrors SquareOrderMappingsController exactly.
+    class SquareTaxRatesController < ResourceController
+      def model_class
+        Spree::TaxRate
+      end
+
+      private
+
+      # `scope`, not `collection` — collection is ResourceController's full
+      # ransack+pagination pipeline (search_collection.result...pagy), and
+      # overriding it directly skips building @search, which is exactly
+      # what `render_table`'s search_form_for needs. `scope` is the one
+      # documented extension point for narrowing the base query before
+      # ransack/pagination run. Scoped here so this page only ever shows
+      # rates this extension actually created (via
+      # SpreeSquare::TaxCategoryMapping), not any rate a store admin might
+      # separately hand-create in the regular Spree tax-rates admin page.
+      def scope
+        Spree::TaxRate.where(id: SpreeSquare::TaxCategoryMapping.select(:tax_rate_id))
+      end
+    end
+  end
+end

data/app/models/spree_square/tax_category_mapping.rb

@@ -0,0 +1,24 @@
+module SpreeSquare
+  # Join row: "in this Spree::TaxCategory, this Square tax is represented by
+  # this Spree::TaxRate." A composite category (an item carrying more than
+  # one Square tax at once) has one row per constituent tax. See
+  # CatalogObjectMapper#resolve_tax_category for how this is used to
+  # find-or-create the right category for an item's exact set of Square tax
+  # ids, and TaxMapping for why this can't just be a belongs_to on
+  # TaxMapping itself (one Square tax can back rates in more than one
+  # category).
+  class TaxCategoryMapping < Spree.base_class
+    self.table_name = 'spree_square_tax_category_mappings'
+
+    # `with_deleted` (mirrors Spree::TaxRate's own belongs_to :tax_category)
+    # — without it, a soft-deleted (disabled-in-Square) rate becomes
+    # unreachable through this association, which would break re-enabling
+    # it later: CatalogObjectMapper#sync_enabled_state! needs to find and
+    # restore the very row it previously destroyed.
+    belongs_to :tax_category, class_name: 'Spree::TaxCategory'
+    belongs_to :tax_mapping, class_name: 'SpreeSquare::TaxMapping'
+    belongs_to :tax_rate, -> { with_deleted }, class_name: 'Spree::TaxRate'
+
+    validates :tax_mapping_id, uniqueness: { scope: :tax_category_id }
+  end
+end

data/app/models/spree_square/tax_mapping.rb

@@ -0,0 +1,24 @@
+module SpreeSquare
+  # Mirrors one Square CatalogTax object — a plain flat percentage + an
+  # inclusion type, category-agnostic. Square's Catalog API has no concept
+  # of jurisdiction/zone at all, so this row never points at a
+  # Spree::TaxRate directly: which Spree::TaxCategory (and therefore which
+  # Spree::TaxRate) a given Square tax participates in depends on which
+  # *combination* of Square taxes each item carries — see
+  # TaxCategoryMapping and CatalogObjectMapper#resolve_tax_category.
+  #
+  # `square_version` is Square's optimistic-concurrency token — same
+  # stale-check pattern as CatalogMapping, guards against out-of-order or
+  # duplicate webhook delivery re-processing older data over newer.
+  class TaxMapping < Spree.base_class
+    self.table_name = 'spree_square_tax_mappings'
+
+    has_many :tax_category_mappings, class_name: 'SpreeSquare::TaxCategoryMapping', dependent: :destroy
+
+    validates :square_tax_id, presence: true, uniqueness: true
+
+    def stale?(incoming_version)
+      square_version.present? && incoming_version.present? && incoming_version <= square_version
+    end
+  end
+end

data/app/services/spree_square/catalog_importer.rb

@@ -1,12 +1,12 @@
 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.
+  # Full catalog import: pulls every ITEM + CATEGORY + MODIFIER_LIST + TAX
+  # from Square (with related objects — images, referenced categories —
+  # inlined via `include_related_objects`) and upserts them into Spree via
+  # CatalogObjectMapper. Categories, modifier lists, and taxes are imported
+  # before items so an item can resolve its `category_id` /
+  # `modifier_list_info` / `tax_ids` to an already-mapped record.
   class CatalogImporter
-    Result = Struct.new(:categories_count, :modifier_lists_count, :items_count, keyword_init: true)
+    Result = Struct.new(:categories_count, :modifier_lists_count, :taxes_count, :items_count, keyword_init: true)
 
     def self.call = new.call
 
@@ -17,14 +17,17 @@ module SpreeSquare
       by_type = objects.group_by(&:type)
       categories = by_type.fetch('CATEGORY', [])
       modifier_lists = by_type.fetch('MODIFIER_LIST', [])
+      taxes = by_type.fetch('TAX', [])
       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) }
+      taxes.each { |tax| mapper.map_tax(tax) }
       items.each { |item| mapper.map_item(item) }
 
-      Result.new(categories_count: categories.size, modifier_lists_count: modifier_lists.size, items_count: items.size)
+      Result.new(categories_count: categories.size, modifier_lists_count: modifier_lists.size,
+                 taxes_count: taxes.size, items_count: items.size)
     end
 
     private
@@ -39,7 +42,7 @@ module SpreeSquare
 
       loop do
         response = client.catalog.search(
-          object_types: %w[ITEM CATEGORY MODIFIER_LIST],
+          object_types: %w[ITEM CATEGORY MODIFIER_LIST TAX],
           include_related_objects: true,
           cursor: cursor
         )

data/app/services/spree_square/catalog_object_mapper.rb

@@ -75,6 +75,46 @@ module SpreeSquare
       modifier
     end
 
+    # Upserts a Square CatalogTax into SpreeSquare::TaxMapping — a pure
+    # mirror (percentage/inclusion/enabled), category-agnostic. Which
+    # Spree::TaxCategory (and therefore Spree::TaxRate) this tax actually
+    # backs is resolved per-item in map_item, since that depends on which
+    # *combination* of taxes each item carries — see resolve_tax_category.
+    def map_tax(square_object)
+      data = square_object.tax_data
+      mapping = SpreeSquare::TaxMapping.find_or_initialize_by(square_tax_id: square_object.id)
+      return mapping if mapping.persisted? && mapping.stale?(square_object.version)
+
+      was_enabled = mapping.persisted? ? mapping.enabled : nil
+      mapping.name = data.name.presence || 'Square Tax'
+      mapping.percentage = data.percentage.presence&.to_d || 0
+      mapping.included_in_price = (data.inclusion_type == 'INCLUSIVE')
+      mapping.enabled = data.enabled != false
+      mapping.square_version = square_object.version
+      mapping.last_synced_at = Time.current
+      mapping.save!
+
+      # Enable/disable first — a re-enable rebuilds the rate's calculator
+      # (see sync_enabled_state!'s own comment for why that's needed), which
+      # the amount/inclusion sync below depends on being present.
+      sync_enabled_state!(mapping, was_enabled)
+
+      # Already-materialized (and currently live) rates mirror any
+      # percentage/inclusion/name change immediately — Square is the source
+      # of truth here, these rows are never hand-edited in Spree. A rate
+      # that's still disabled is skipped: no live TaxRate exists for it to
+      # update, and the next enable will rebuild it fresh from this mapping
+      # anyway.
+      mapping.tax_category_mappings.includes(:tax_rate).each do |tcm|
+        rate = tcm.tax_rate
+        next unless rate && !rate.paranoia_destroyed?
+
+        rate.update!(amount: mapping.percentage / 100.0, included_in_price: mapping.included_in_price, name: mapping.name)
+      end
+
+      mapping
+    end
+
     def map_item(square_object)
       data = square_object.item_data
       mapping = SpreeSquare::CatalogMapping.find_or_initialize_by(
@@ -91,6 +131,7 @@ module SpreeSquare
       )
       product.name = data.name.presence || 'Untitled item'
       product.description = data.description
+      product.tax_category = resolve_tax_category(data)
       product.save!
 
       publish!(product)
@@ -222,5 +263,122 @@ module SpreeSquare
       base = name.presence || 'item'
       "#{base.parameterize}-#{square_id.downcase}"
     end
+
+    # Enable/disable is the one thing that can't just be "update the row" —
+    # a disabled Square tax must stop applying everywhere it appears, and a
+    # re-enabled one must resume applying with no re-import of the items
+    # that reference it. Spree::TaxRate is acts_as_paranoid, so soft-delete/
+    # restore is exactly "stop/resume applying" — Spree's own
+    # TaxRate.potential_rates_for_zone already excludes deleted rows via its
+    # default scope, no other code needs to know about this.
+    def sync_enabled_state!(mapping, was_enabled)
+      return if was_enabled == mapping.enabled
+
+      mapping.tax_category_mappings.each do |tcm|
+        rate = tcm.tax_rate
+        next unless rate
+
+        if mapping.enabled
+          next unless rate.paranoia_destroyed?
+
+          rate.restore(recursive: true)
+          # Spree::TaxRate's `has_one :calculator, dependent: :destroy` is a
+          # REAL (hard) destroy even when the owning TaxRate is only
+          # soft-deleted — acts_as_paranoid intercepts the TaxRate's own row,
+          # not its dependent-destroy callbacks. So a restored rate has no
+          # calculator left to restore; rebuild it, or `TaxRate.adjust`'s
+          # `delegate :compute, to: :calculator` raises on the next order
+          # recalculation.
+          rate.calculator_type = 'Spree::Calculator::DefaultTax' if rate.calculator.nil?
+          rate.save!
+        elsif !rate.paranoia_destroyed?
+          rate.destroy
+        end
+      end
+    end
+
+    # Resolves an item's exact set of Square tax_ids to the Spree::TaxCategory
+    # that represents that combination — creating it (and the underlying
+    # Spree::TaxRate(s), one per constituent Square tax) the first time this
+    # exact combination is seen. See TaxCategoryMapping for why a composite
+    # category can need more than one row here.
+    def resolve_tax_category(item_data)
+      square_tax_ids = Array(item_data.tax_ids)
+      return non_taxable_category if square_tax_ids.empty?
+
+      tax_mappings = SpreeSquare::TaxMapping.where(square_tax_id: square_tax_ids).to_a
+      # Item references a tax id this store hasn't synced yet (import order,
+      # or the tax was deleted in Square) — fall back to non-taxable rather
+      # than guessing; a later re-import (taxes always run before items)
+      # will resolve it correctly once the tax itself is known.
+      return non_taxable_category if tax_mappings.empty?
+
+      existing_category_id = matching_composite_category_id(tax_mappings)
+      return Spree::TaxCategory.find(existing_category_id) if existing_category_id
+
+      create_composite_tax_category!(tax_mappings)
+    end
+
+    def matching_composite_category_id(tax_mappings)
+      target_ids = tax_mappings.map(&:id)
+      candidates = SpreeSquare::TaxCategoryMapping.where(tax_mapping_id: target_ids)
+                                                    .group(:tax_category_id)
+                                                    .having('COUNT(*) = ?', target_ids.size)
+                                                    .pluck(:tax_category_id)
+
+      # The HAVING above only proves the candidate contains at least
+      # `target_ids.size` of OUR mappings — it doesn't rule out the
+      # candidate having MORE members than that (a superset, e.g. a
+      # 3-tax category when the item only carries 2 of those taxes).
+      # Confirm an exact match before reusing it.
+      candidates.find do |tax_category_id|
+        SpreeSquare::TaxCategoryMapping.where(tax_category_id: tax_category_id).count == target_ids.size
+      end
+    end
+
+    def create_composite_tax_category!(tax_mappings)
+      zone = tax_zone!
+      name = tax_mappings.map(&:name).join(' + ').presence || 'Square Tax'
+      category = Spree::TaxCategory.find_by(name: name) || Spree::TaxCategory.create!(name: name)
+
+      tax_mappings.each do |tm|
+        next if SpreeSquare::TaxCategoryMapping.exists?(tax_category_id: category.id, tax_mapping_id: tm.id)
+
+        rate = Spree::TaxRate.create!(
+          zone: zone,
+          tax_category: category,
+          name: tm.name,
+          amount: (tm.percentage || 0) / 100.0,
+          included_in_price: tm.included_in_price,
+          calculator_type: 'Spree::Calculator::DefaultTax'
+        )
+        SpreeSquare::TaxCategoryMapping.create!(tax_category: category, tax_mapping: tm, tax_rate: rate)
+      end
+
+      category
+    end
+
+    def non_taxable_category
+      @non_taxable_category ||= Spree::TaxCategory.find_by(name: 'Non-taxable') ||
+                                 Spree::TaxCategory.create!(name: 'Non-taxable')
+    end
+
+    # The store's own tax Zone, set up once via `spree_square:ensure_tax_zone`
+    # (Square's Catalog API has no jurisdiction concept to sync — this is
+    # entirely Spree-side). Raises rather than silently skipping: importing
+    # a real tax with no zone to attach it to is a setup error, not a
+    # recoverable no-op.
+    def tax_zone!
+      @tax_zone ||= begin
+        state = Spree::StockLocation.find_by(default: true)&.state
+        zone = state && Spree::Zone.where(kind: 'state')
+                                    .joins(:zone_members)
+                                    .where(spree_zone_members: { zoneable_type: 'Spree::State', zoneable_id: state.id })
+                                    .first
+        raise "No tax Zone found for the store's state — run `bin/rails spree_square:ensure_tax_zone` first." if zone.blank?
+
+        zone
+      end
+    end
   end
 end

data/app/views/spree/admin/square_tax_rates/index.html.erb

@@ -0,0 +1,5 @@
+<% content_for :page_title do %>
+  Square Tax Rates
+<% end %>
+
+<%= render_table @collection, :square_tax_rates %>

data/config/initializers/spree_admin_square_navigation.rb

@@ -22,4 +22,20 @@ Rails.application.config.after_initialize do
     position: 67,
     active: -> { controller_name == 'square_oauth' },
     if: -> { can?(:manage, SpreeSquare::Credential) }
+
+  # Position 75 — confirmed free at the time this was added by checking
+  # every nav initializer across this project: spree_square itself (65-67,
+  # above), spree_doordash (68-70), spree_menu_chat (71-72), spree_loyalty
+  # (73-74), plus spree_host's own host-local
+  # admin_square_modifier_lists_navigation.rb (73 — a pre-existing
+  # collision with spree_loyalty's 73, not this extension's to fix).
+  # Confirm the actual current highest position the same way before adding
+  # another nav item anywhere in this project.
+  Spree.admin.navigation.sidebar.add :square_tax_rates,
+    label: 'Square Tax Rates',
+    url: :admin_square_tax_rates_path,
+    icon: 'percentage',
+    position: 75,
+    active: -> { controller_name == 'square_tax_rates' },
+    if: -> { can?(:manage, Spree::TaxRate) }
 end

data/config/initializers/spree_admin_square_tables.rb

@@ -92,4 +92,52 @@ Rails.application.config.after_initialize do
     filterable: false,
     default: true,
     position: 50
+
+  # new_resource: false — read-only, same reason as every table above (no
+  # :new/:create route; only: [:index] in config/routes.rb).
+  Spree.admin.tables.register(:square_tax_rates, model_class: Spree::TaxRate,
+                                                   search_param: :name_cont, new_resource: false)
+
+  Spree.admin.tables.square_tax_rates.add :name,
+    label: :name,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 10
+
+  Spree.admin.tables.square_tax_rates.add :amount_percentage,
+    label: :rate,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 20,
+    method: ->(rate) { "#{rate.amount_percentage}%" }
+
+  Spree.admin.tables.square_tax_rates.add :zone,
+    label: :zone,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 30,
+    method: ->(rate) { rate.zone&.name }
+
+  Spree.admin.tables.square_tax_rates.add :tax_category,
+    label: :tax_category,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 40,
+    method: ->(rate) { rate.tax_category&.name }
+
+  Spree.admin.tables.square_tax_rates.add :updated_at,
+    label: :last_synced,
+    type: :datetime,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 50
 end

data/config/routes.rb

@@ -13,6 +13,7 @@ Spree::Core::Engine.add_routes do
   namespace :admin do
     resources :square_order_mappings, only: [:index]
     resources :square_webhook_events, only: [:index]
+    resources :square_tax_rates, only: [:index]
 
     # Self-service OAuth connection (see Spree::Admin::SquareOauthController).
     # Explicit named routes rather than `resource :square_oauth` — the

data/db/migrate/20260820180001_create_spree_square_tax_mappings.rb

@@ -0,0 +1,22 @@
+class CreateSpreeSquareTaxMappings < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_square_tax_mappings do |t|
+      t.string :square_tax_id, null: false
+      t.string :name
+      # Mirrors what Square itself stores: a plain decimal percentage
+      # (e.g. 8.0, not 0.08) — kept alongside the derived Spree::TaxRate(s)
+      # so re-imports can detect a no-op without re-deriving from a rate.
+      t.decimal :percentage, precision: 8, scale: 5
+      t.boolean :included_in_price, default: false, null: false
+      t.boolean :enabled, default: true, null: false
+      # Square's optimistic-concurrency token — same stale-check pattern as
+      # CatalogMapping, guards against out-of-order webhook delivery.
+      t.bigint :square_version
+      t.datetime :last_synced_at
+
+      t.timestamps
+    end
+
+    add_index :spree_square_tax_mappings, :square_tax_id, unique: true
+  end
+end

data/db/migrate/20260820180002_create_spree_square_tax_category_mappings.rb

@@ -0,0 +1,23 @@
+class CreateSpreeSquareTaxCategoryMappings < ActiveRecord::Migration[8.1]
+  def change
+    # A single Square tax can back tax rates in more than one Spree tax
+    # category — e.g. item A carries only "Sales Tax", item B carries
+    # "Sales Tax" + "Bottle Tax" together, so "Sales Tax" needs its own
+    # Spree::TaxRate under each of the two resulting composite categories.
+    # This join records, for one (tax_category, square tax) pair, which
+    # Spree::TaxRate row represents it — the lookup CatalogObjectMapper
+    # uses to find-or-create the right composite Spree::TaxCategory for an
+    # item's exact set of Square tax ids, without any schema change to
+    # core's spree_tax_categories/spree_tax_rates tables.
+    create_table :spree_square_tax_category_mappings do |t|
+      t.references :tax_category, null: false, foreign_key: { to_table: :spree_tax_categories }
+      t.references :tax_mapping, null: false, foreign_key: { to_table: :spree_square_tax_mappings }
+      t.references :tax_rate, null: false, foreign_key: { to_table: :spree_tax_rates }
+
+      t.timestamps
+    end
+
+    add_index :spree_square_tax_category_mappings, %i[tax_category_id tax_mapping_id],
+              unique: true, name: 'index_square_tax_category_mappings_on_category_and_tax'
+  end
+end

data/lib/spree_square/version.rb

@@ -1,5 +1,5 @@
 module SpreeSquare
-  VERSION = '0.1.2'.freeze
+  VERSION = '0.2.0'.freeze
 
   def gem_version
     Gem::Version.new(VERSION)

data/lib/tasks/spree_square.rake

@@ -74,4 +74,86 @@ namespace :spree_square do
     puts '---'
     puts 'Set SQUARE_WEBHOOK_SIGNATURE_KEY in .env to the value above, then recreate the web container.'
   end
+
+  desc "Phase 8 M1: ensure a state-scoped tax Zone exists for the store's own StockLocation state"
+  task ensure_tax_zone: :environment do
+    stock_location = Spree::StockLocation.find_by(default: true)
+    abort 'No default Spree::StockLocation found.' if stock_location.blank?
+
+    state = stock_location.state
+    abort "StockLocation ##{stock_location.id} (#{stock_location.name}) has no state set — set one before running this task." if state.blank?
+
+    # Named/keyed off the state itself (not hardcoded "OH") and re-derived
+    # from StockLocation on every run — if that address ever moves to a
+    # different state, re-running this task points the zone at the new one
+    # instead of silently leaving a stale zone behind.
+    zone = Spree::Zone.find_or_initialize_by(name: "#{state.abbr} Sales Tax")
+    zone.kind = 'state'
+    zone.description = "Sales tax zone for #{state.name} — tracks Spree::StockLocation's own state; see spree_square:ensure_tax_zone." if zone.has_attribute?(:description)
+    zone.save!
+    zone.state_ids = [state.id]
+
+    puts "Zone ##{zone.id} '#{zone.name}' now contains exactly: #{zone.states.pluck(:abbr).join(', ')}"
+  end
+
+  desc 'Phase 8 M4: create a real 8% Sales Tax object in Square Sandbox, attach it to every item, and tax delivery fees to match'
+  task setup_demo_tax: :environment do
+    # credential: nil forces the SQUARE_ACCESS_TOKEN env fallback instead of
+    # this store's connected OAuth credential — the OAuth connection was
+    # authorized without ITEMS_WRITE (confirmed live: its scopes list is
+    # MERCHANT_PROFILE_READ/ITEMS_READ/INVENTORY_*/ORDERS_*/PAYMENTS_*, no
+    # ITEMS_WRITE), the same scope seed_demo_menu.rake's item-creation
+    # calls need. A one-time catalog-admin task like this one reasonably
+    # uses the broader sandbox token rather than re-running the OAuth
+    # consent flow just to add a scope.
+    client = SpreeSquare::Client.new(credential: nil)
+
+    puts 'Creating "Sales Tax" (8.0%) catalog object in Square...'
+    response = client.catalog.batch_upsert(
+      idempotency_key: SecureRandom.uuid,
+      batches: [{
+        objects: [{
+          type: 'TAX',
+          id: '#tax-sales-tax',
+          tax_data: {
+            name: 'Sales Tax',
+            calculation_phase: 'TAX_SUBTOTAL_PHASE',
+            inclusion_type: 'ADDITIVE',
+            percentage: '8.0',
+            applies_to_custom_amounts: true,
+            enabled: true
+          }
+        }]
+      }]
+    )
+    tax_id = response.id_mappings.find { |m| m.client_object_id == '#tax-sales-tax' }&.object_id_
+    abort 'Square did not return an id for the new tax object.' if tax_id.blank?
+    puts "Created tax #{tax_id}"
+
+    item_ids = client.catalog.search(object_types: ['ITEM']).objects.to_a.map(&:id)
+    abort 'No items found in the Square catalog — run spree_square:seed_demo_menu first.' if item_ids.empty?
+
+    puts "Attaching to #{item_ids.size} item(s)..."
+    client.catalog.update_item_taxes(item_ids: item_ids, taxes_to_enable: [tax_id])
+
+    puts 'Waiting for Square search index to catch up...'
+    sleep 20
+
+    puts 'Importing into Spree...'
+    result = SpreeSquare::CatalogImporter.call
+    puts "Imported #{result.taxes_count} tax(es) and re-synced #{result.items_count} item(s)."
+
+    tax_mapping = SpreeSquare::TaxMapping.find_by(square_tax_id: tax_id)
+    tax_category = tax_mapping&.tax_category_mappings&.first&.tax_category
+    if tax_category.blank?
+      puts 'Warning: could not resolve the resulting Spree::TaxCategory — did any item actually import with this tax attached?'
+    else
+      # Square's Catalog API has no concept of a delivery fee at all — this
+      # part is Spree-only, applying the same tax category to every
+      # shipping method per the confirmed decision (delivery fee taxed the
+      # same as food).
+      count = Spree::ShippingMethod.update_all(tax_category_id: tax_category.id)
+      puts "Set tax_category '#{tax_category.name}' on #{count} shipping method(s): #{Spree::ShippingMethod.pluck(:name).join(', ')}"
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spree_square
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Amit Solanki
@@ -121,6 +121,7 @@ files:
 - app/assets/images/.keep
 - app/controllers/spree/admin/square_oauth_controller.rb
 - app/controllers/spree/admin/square_order_mappings_controller.rb
+- app/controllers/spree/admin/square_tax_rates_controller.rb
 - app/controllers/spree/admin/square_webhook_events_controller.rb
 - app/controllers/spree_square/webhooks_controller.rb
 - app/javascript/spree_square/application.js
@@ -141,6 +142,8 @@ files:
 - app/models/spree_square/modifier_list.rb
 - app/models/spree_square/order_mapping.rb
 - app/models/spree_square/product_modifier_list.rb
+- app/models/spree_square/tax_category_mapping.rb
+- app/models/spree_square/tax_mapping.rb
 - app/models/spree_square/taxon_mapping.rb
 - app/models/spree_square/webhook_event.rb
 - app/serializers/spree_square/line_item_serializer.rb
@@ -161,6 +164,7 @@ files:
 - app/subscribers/spree_square/order_completed_subscriber.rb
 - app/views/spree/admin/square_oauth/show.html.erb
 - app/views/spree/admin/square_order_mappings/index.html.erb
+- app/views/spree/admin/square_tax_rates/index.html.erb
 - app/views/spree/admin/square_webhook_events/index.html.erb
 - bin/importmap
 - bin/rails
@@ -181,6 +185,8 @@ files:
 - db/migrate/20260809160004_create_spree_square_line_item_modifiers.rb
 - db/migrate/20260809170001_create_spree_square_order_mappings.rb
 - db/migrate/20260810180001_create_spree_square_credentials.rb
+- db/migrate/20260820180001_create_spree_square_tax_mappings.rb
+- db/migrate/20260820180002_create_spree_square_tax_category_mappings.rb
 - lib/generators/spree_square/install/install_generator.rb
 - lib/spree_square.rb
 - lib/spree_square/configuration.rb