spree_square 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1bcb9058e713d818be55281c3643f158f79b43576d432f3a365d4b3a83e94c7a
+  data.tar.gz: 4ef13d373d9a2065f6103a824b365ed9427bb6c93f5bb93fc222615448ae9d32
+SHA512:
+  metadata.gz: b26da9d8e6d45cc8d26c67f0b6100aeab3bb46a8dbacfaa2f5c8725c06abde9df744be9170c75bb7c4ad398df4a5c628b3f316ebb0ac17ef4ecd2ba16cfbcdb0
+  data.tar.gz: 0340e00a33c32b51058bb716f4386630d3fa76c1974a98d84c0cea6fe38e6999e2a1ddb29edd25619dd870061a34b633b276ba28cf217cf43efc46e9fef6913f

data/.env

@@ -0,0 +1,7 @@
+# Loaded via `dotenv/load` in spec/spec_helper.rb, for the dummy test app
+# only — not read by anything that ships. Test-only Active Record Encryption
+# keys (SpreeSquare::Credential) so specs can save/load encrypted columns;
+# generated with SecureRandom, no real secret behind them.
+ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=2Ewc8daKheOnrlLa1eN1JKvPj4IiCj2f
+ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=yEjwBJYcxLgE3yP5mD98YVTQMTMzNHix
+ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=8CO9MySzjX3gCDsPB69dhfTiWpIKIigh

data/.gem_release.yml

@@ -0,0 +1,3 @@
+bump:
+  file: "lib/spree_square/version.rb"
+

data/.github/.dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "bundler" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

data/.github/workflows/tests.yml

@@ -0,0 +1,107 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test-postgres:
+    name: "PostgreSQL"
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      DB: postgres
+      DB_HOST: localhost
+      DB_USERNAME: postgres
+      DB_PASSWORD: postgres
+      BUNDLE_JOBS: 4
+      BUNDLE_RETRY: 3
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Install libvips
+        run: sudo apt-get update && sudo apt-get install -y libvips-dev
+
+      - name: Create test app
+        run: bundle exec rake test_app
+
+      - name: Run tests
+        run: bundle exec rspec --format documentation
+
+  test-mysql:
+    name: "MySQL"
+    runs-on: ubuntu-latest
+    services:
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: password
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd="mysqladmin ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      DB: mysql
+      DB_HOST: 127.0.0.1
+      DB_USERNAME: root
+      DB_PASSWORD: password
+      BUNDLE_JOBS: 4
+      BUNDLE_RETRY: 3
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Install libvips
+        run: sudo apt-get update && sudo apt-get install -y libvips-dev
+
+      - name: Create test app
+        run: bundle exec rake test_app
+
+      - name: Run tests
+        run: bundle exec rspec --format documentation
+
+  brakeman:
+    name: Brakeman
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Run Brakeman
+        run: bundle exec brakeman --exit-on-warn --exit-on-error

data/.gitignore

@@ -0,0 +1,23 @@
+\#*
+*~
+.#*
+.DS_Store
+.idea
+.localeapp/locales
+.project
+.vscode
+coverage
+default
+Gemfile.lock
+tmp
+nbproject
+pkg
+*.sw?
+spec/dummy
+.rvmrc
+.sass-cache
+public/spree
+.ruby-version
+.ruby-gemset
+*.gem
+*/*.gem

data/.rspec

@@ -0,0 +1,3 @@
+--color
+-r spec_helper
+-f documentation

data/.rubocop.yml

@@ -0,0 +1,24 @@
+plugins:
+  - rubocop-rails
+
+AllCops:
+  DisplayCopNames: true
+  TargetRubyVersion: 3.2
+  Include:
+    - '**/Gemfile'
+    - '**/Rakefile'
+    - '**/Appraisals'
+  Exclude:
+    - 'spec/dummy/**/*'
+    - 'lib/generators/**/*'
+
+Layout/LineLength:
+  Max: 150
+
+# DISABLED
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## 0.1.0
+
+Initial public release.
+
+- Square catalog sync (items, variations, categories, images, modifier lists) into Spree, via a
+  full importer and real-time webhooks (`catalog.version.updated`, `inventory.count.updated`).
+- Order push: completed Spree orders are pushed into Square as paid tickets (`EXTERNAL` payment),
+  targeting the Square location mapped from the order's stock location.
+- Order status sync-back: `order.updated` / `order.fulfillment.updated` webhooks keep the Spree
+  order's shipment/cancellation state in sync with Square.
+- Self-service OAuth ("Connect to Square" in the admin) alongside a hand-issued
+  `SQUARE_ACCESS_TOKEN` for local development — see the README's "Connecting to Square" section.
+- Nightly reconciliation job, dead-letter alerting on failed order pushes, and admin pages listing
+  order mappings and webhook events for support visibility.

data/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Thanks for considering a contribution to `spree_square`.
+
+## Getting set up
+
+```bash
+bundle install
+bundle exec rake test_app   # generates spec/dummy, the Rails app specs run against
+bundle exec rspec
+```
+
+## Making a change
+
+1. Open an issue first for anything beyond a small fix, so the approach can be discussed before
+   you put time into it.
+2. Add or update specs alongside any behavior change — `bundle exec rspec` should stay green.
+3. Keep decorators as a last resort (see the main README's customization pattern order); prefer
+   Spree's Events/Subscribers or Dependencies mechanisms where they fit.
+4. Open a pull request describing what changed and why.
+
+## Releasing (maintainers)
+
+```bash
+bundle exec gem bump --version [major|minor|patch] -t -m "Release v%s"
+bundle exec gem release
+```
+
+See the [gem-release README](https://github.com/svenfuchs/gem-release) for more options.

data/Gemfile

@@ -0,0 +1,28 @@
+source 'https://rubygems.org'
+
+gem 'rails-controller-testing'
+
+# Pinned to the released 5.6.x line (matching spree_host) rather than tracking
+# spree/spree's main branch, which is mid-refactor toward v6 (e.g. spree_admin
+# has moved around between tags and main) and isn't safe to develop against.
+spree_opts = if ENV['SPREE_PATH']
+                { 'path': ENV['SPREE_PATH'] }
+             else
+                '~> 5.6.0'
+             end
+gem 'spree', spree_opts
+gem 'spree_admin', spree_opts
+
+gem 'spree_dev_tools', '>= 0.6.0.rc1'
+
+if ENV['DB'] == 'mysql'
+  gem 'mysql2'
+elsif ENV['DB'] == 'postgres'
+  gem 'pg'
+else
+  gem 'sqlite3'
+end
+
+gem 'propshaft'
+
+gemspec

data/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Amit Solanki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,105 @@
+# Spree Square
+
+This is a Square extension for [Spree Commerce](https://spreecommerce.org), an open source e-commerce platform built with Ruby on Rails.
+
+## Installation
+
+1. Add this extension to your Gemfile with this line:
+
+    ```ruby
+    bundle add spree_square
+    ```
+
+2. Run the install generator
+
+    ```ruby
+    bundle exec rails g spree_square:install
+    ```
+
+3. Restart your server
+
+  If your server was running, restart it so that it can find the assets properly.
+
+## Connecting to Square
+
+Two ways to authenticate, in order of preference:
+
+### OAuth — "Connect to Square" (recommended)
+
+Lets a store owner connect their own Square account from the Spree admin, without you
+hand-generating an access token for them. This is also the auth model Square requires before
+an app can be listed on the App Marketplace — personal access tokens are explicitly disallowed
+for multi-merchant use.
+
+One-time setup, per environment (sandbox and production each need their own app):
+
+1. Go to the [Square Developer Dashboard](https://developer.squareup.com/apps) and open (or
+   create) an Application.
+2. On its **OAuth** page, add a redirect URL:
+   `https://your-store.example.com/admin/square_oauth/callback` (must be `https` in production;
+   `http://localhost:3000/admin/square_oauth/callback` is fine for local dev).
+3. Copy the **Application ID** (same value you'd use for `SQUARE_APPLICATION_ID`) and the
+   **Application Secret**, and set both in `.env`:
+
+   ```
+   SQUARE_APPLICATION_ID=sandbox-sq0idb-...
+   SQUARE_APPLICATION_SECRET=sq0csp-...
+   ```
+
+4. Recreate (not just restart) the container so the new `.env` values actually load —
+   `docker compose up -d web`, not `docker compose restart web`; Compose only re-reads `.env` on
+   the former.
+5. In the Spree admin, go to **Square Connection** in the sidebar and click **Connect to
+   Square**.
+
+Tokens are stored per-store in `SpreeSquare::Credential`, encrypted at rest (Active Record
+Encryption — keys generated once via `bin/rails db:encryption:init`, wired up in
+`lib/spree_square/engine.rb`, sourced from `ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY` /
+`_DETERMINISTIC_KEY` / `_KEY_DERIVATION_SALT` in `.env`). `SpreeSquare::Client` refreshes the
+access token automatically whenever it's within Square's recommended 7-day renewal window
+(tokens expire every 30 days) — no cron job or manual step needed once connected.
+
+### `SQUARE_ACCESS_TOKEN` — direct token (dev/sandbox fallback)
+
+The original single-tenant path: generate a token yourself from the Developer Dashboard and set
+`SQUARE_ACCESS_TOKEN` in `.env`. `SpreeSquare::Client` falls back to this automatically for any
+store that hasn't connected via OAuth — convenient for local development, but not something
+Square allows for real multi-merchant production use.
+
+## Developing
+
+1. Create a dummy app
+
+    ```bash
+    bundle update
+    bundle exec rake test_app
+    ```
+
+2. Add your new code
+3. Run tests
+
+    ```bash
+    bundle exec rspec
+    ```
+
+When testing your applications integration with this extension you may use it's factories.
+Simply add this require statement to your spec_helper:
+
+```ruby
+require 'spree_square/factories'
+```
+
+## Releasing a new version
+
+```shell
+bundle exec gem bump -p -t
+bundle exec gem release
+```
+
+For more options please see [gem-release README](https://github.com/svenfuchs/gem-release)
+
+## Contributing
+
+If you'd like to contribute, please take a look at the
+[instructions](CONTRIBUTING.md) for installing dependencies and crafting a good
+pull request.

data/Rakefile

@@ -0,0 +1,23 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+require 'spree/testing_support/extension_rake'
+
+RSpec::Core::RakeTask.new
+
+task :default do
+  if Dir['spec/dummy'].empty?
+    Rake::Task[:test_app].invoke
+    Dir.chdir('../../')
+  end
+  Rake::Task[:spec].invoke
+end
+
+desc 'Generates a dummy app for testing'
+task :test_app do
+  ENV['LIB_NAME'] = 'spree_square'
+  Rake::Task['extension:test_app'].execute(
+    install_admin: true
+  )
+end

data/app/assets/config/spree_square_manifest.js

@@ -0,0 +1,5 @@
+//= link_tree ../images
+//= link spree_square/application.js
+//= link_tree ../../javascript/spree_square/controllers .js
+//= link_tree ../../../vendor/javascript .js
+//= link_tree ../../../vendor/stylesheets .css

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

@@ -0,0 +1,103 @@
+module Spree
+  module Admin
+    # Self-service "Connect to Square" flow for the current store — the
+    # OAuth replacement for hand-generating SQUARE_ACCESS_TOKEN in .env.
+    # Square requires multi-merchant apps to use OAuth rather than personal
+    # access tokens (a prerequisite for App Marketplace listing), and this is
+    # the admin-facing half of that: authorize -> callback -> store an
+    # encrypted SpreeSquare::Credential -> SpreeSquare::Client picks it up
+    # automatically from here on (see Client.for_store).
+    class SquareOauthController < Spree::Admin::BaseController
+      before_action :ensure_oauth_configured, only: %i[connect callback]
+
+      def show
+        @credential = SpreeSquare::Credential.find_by(store: current_store)
+      end
+
+      # Kicks off the OAuth authorization-code flow: redirect the admin's
+      # browser to Square's own consent page. `state` is a CSRF token,
+      # verified on the way back in #callback — without it, an attacker
+      # could trick an admin into connecting *the attacker's* Square account
+      # to this store by crafting their own callback link.
+      def connect
+        state = SecureRandom.hex(24)
+        session[:square_oauth_state] = state
+
+        redirect_to SpreeSquare::OauthClient.authorize_url(
+          redirect_uri: admin_callback_square_oauth_url,
+          state: state
+        ), allow_other_host: true
+      end
+
+      def callback
+        expected_state = session.delete(:square_oauth_state)
+
+        if params[:error].present?
+          flash[:error] = Spree.t(:square_oauth_denied, default: "Square authorization was cancelled: #{params[:error_description] || params[:error]}")
+          return redirect_to admin_square_oauth_path
+        end
+
+        if expected_state.blank? || !ActiveSupport::SecurityUtils.secure_compare(expected_state, params[:state].to_s)
+          flash[:error] = Spree.t(:square_oauth_state_mismatch, default: 'Square authorization could not be verified (invalid state) — please try connecting again.')
+          return redirect_to admin_square_oauth_path
+        end
+
+        response = SpreeSquare::OauthClient.exchange_code(code: params[:code], redirect_uri: admin_callback_square_oauth_url)
+        save_credential!(response)
+
+        flash[:success] = Spree.t(:square_oauth_connected, default: 'Connected to Square.')
+        redirect_to admin_square_oauth_path
+      rescue Square::Errors::ResponseError => e
+        Rails.logger.error("[SpreeSquare] OAuth token exchange failed: #{e.message}")
+        flash[:error] = Spree.t(:square_oauth_exchange_failed, default: 'Could not connect to Square — please try again.')
+        redirect_to admin_square_oauth_path
+      end
+
+      def destroy
+        credential = SpreeSquare::Credential.find_by(store: current_store)
+        if credential
+          begin
+            SpreeSquare::OauthClient.revoke(credential)
+          rescue StandardError => e
+            # A failed remote revoke (token already invalid, network blip)
+            # shouldn't trap the admin into a "disconnect" button that never
+            # works — the local side is what actually stops this store's
+            # syncing, so proceed to destroy the row regardless.
+            Rails.logger.warn("[SpreeSquare] OAuth revoke failed, disconnecting locally anyway: #{e.message}")
+          end
+          credential.destroy!
+        end
+
+        flash[:success] = Spree.t(:square_oauth_disconnected, default: 'Disconnected from Square.')
+        redirect_to admin_square_oauth_path
+      end
+
+      private
+
+      def ensure_oauth_configured
+        return if ENV['SQUARE_APPLICATION_SECRET'].present?
+
+        flash[:error] = 'SQUARE_APPLICATION_SECRET is not set — add it to .env first (see spree_square/README.md).'
+        redirect_to admin_square_oauth_path
+      end
+
+      def save_credential!(oauth_response)
+        credential = SpreeSquare::Credential.find_or_initialize_by(store: current_store)
+        credential.assign_attributes(
+          square_merchant_id: oauth_response.merchant_id,
+          square_environment: ENV.fetch('SQUARE_ENVIRONMENT', 'sandbox'),
+          access_token: oauth_response.access_token,
+          refresh_token: oauth_response.refresh_token,
+          expires_at: parse_time(oauth_response.expires_at),
+          refresh_token_expires_at: parse_time(oauth_response.refresh_token_expires_at),
+          scopes: SpreeSquare::OauthClient::SCOPES
+        )
+        credential.save!
+      end
+
+      def parse_time(value)
+        value.present? ? Time.iso8601(value) : nil
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+module Spree
+  module Admin
+    # Read-only support/diagnostic view — no create/edit/destroy, this is
+    # visibility into what spree_square has already done, not a place to
+    # change it. See config/routes.rb (only: [:index]).
+    class SquareOrderMappingsController < ResourceController
+      def model_class
+        SpreeSquare::OrderMapping
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+module Spree
+  module Admin
+    # Read-only support/diagnostic view of every inbound Square webhook —
+    # what arrived, whether it processed, and the error if it didn't.
+    class SquareWebhookEventsController < ResourceController
+      def model_class
+        SpreeSquare::WebhookEvent
+      end
+    end
+  end
+end

data/app/controllers/spree_square/webhooks_controller.rb

@@ -0,0 +1,56 @@
+module SpreeSquare
+  # Receives Square webhook notifications. Square-signature-verified instead
+  # of Spree/Devise-authenticated, and deliberately does the least possible
+  # work synchronously: verify, record, ack, hand off to a job. Square treats
+  # a slow or non-2xx response as a delivery failure and retries.
+  class WebhooksController < ActionController::Base
+    skip_before_action :verify_authenticity_token, raise: false
+
+    def create
+      raw_body = request.raw_post
+      signature = request.headers['x-square-hmacsha256-signature']
+
+      unless SpreeSquare::WebhookVerifier.valid?(
+        url: request.original_url,
+        body: raw_body,
+        signature: signature,
+        signing_key: SpreeSquare::Client.instance.webhook_signature_key
+      )
+        Rails.logger.warn('[SpreeSquare] webhook signature verification failed')
+        return head :unauthorized
+      end
+
+      payload = JSON.parse(raw_body)
+      event = find_or_log_event(payload)
+      enqueue_job(event) if event.previously_new_record?
+
+      head :ok
+    rescue JSON::ParserError
+      head :bad_request
+    end
+
+    private
+
+    def find_or_log_event(payload)
+      SpreeSquare::WebhookEvent.find_or_create_by!(square_event_id: payload['event_id']) do |event|
+        event.event_type = payload['type']
+        event.payload = payload
+      end
+    rescue ActiveRecord::RecordNotUnique, ActiveRecord::RecordInvalid
+      # Lost a race with a concurrent duplicate delivery — the row exists now
+      # either way, and it's already being (or has been) processed once.
+      SpreeSquare::WebhookEvent.find_by!(square_event_id: payload['event_id'])
+    end
+
+    def enqueue_job(event)
+      case event.event_type
+      when 'catalog.version.updated'
+        SpreeSquare::CatalogWebhookJob.perform_later(event.id)
+      when 'inventory.count.updated'
+        SpreeSquare::InventoryWebhookJob.perform_later(event.id)
+      when 'order.updated', 'order.fulfillment.updated'
+        SpreeSquare::OrderWebhookJob.perform_later(event.id)
+      end
+    end
+  end
+end

data/app/javascript/spree_square/application.js

@@ -0,0 +1,16 @@
+import '@hotwired/turbo-rails'
+import { Application } from '@hotwired/stimulus'
+
+let application
+
+if (typeof window.Stimulus === "undefined") {
+  application = Application.start()
+  application.debug = false
+  window.Stimulus = application
+} else {
+  application = window.Stimulus
+}
+
+import SpreeSquareController from 'spree_square/controllers/spree_square_controller' 
+
+application.register('spree_square', SpreeSquareController)

data/app/javascript/spree_square/controllers/spree_square_controller.js

@@ -0,0 +1,7 @@
+import { Controller } from '@hotwired/stimulus'
+
+export default class extends Controller {
+  connect() {
+    console.log('Hello, SpreeSquare!')
+  }
+}

data/app/jobs/spree_square/base_job.rb

@@ -0,0 +1,5 @@
+module SpreeSquare
+  class BaseJob < Spree::BaseJob
+    queue_as SpreeSquare.queue
+  end
+end

data/app/jobs/spree_square/catalog_webhook_job.rb

@@ -0,0 +1,20 @@
+module SpreeSquare
+  # Handles `catalog.version.updated`. Square's payload is deliberately
+  # coarse — it says the catalog changed, not what changed — so the handler
+  # just re-runs a full import. Fine for a restaurant-sized catalog; would
+  # need to become a scoped/incremental fetch for a larger one.
+  class CatalogWebhookJob < BaseJob
+    # A block passed to retry_on runs only once retries are exhausted —
+    # normal transient failures retry silently; only a truly stuck job
+    # reaches here and gets flagged.
+    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: 'catalog_webhook')
+    end
+
+    def perform(webhook_event_id)
+      SpreeSquare::CatalogImporter.call
+      SpreeSquare::WebhookEvent.find(webhook_event_id).mark_processed!
+    end
+  end
+end