Spree Square

This is a Square extension for Spree Commerce, an open source e-commerce platform built with Ruby on Rails.

Installation

Add this extension to your Gemfile with this line:
```
bundle add spree_square
```

Run the install generator

bundle exec rails g spree_square:install

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):

Go to the Square Developer Dashboard and open (or create) an Application.
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).
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-...
```
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.
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

Create a dummy app

bundle update
bundle exec rake test_app

Add your new code
Run tests
```
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:

require 'spree_square/factories'

Releasing a new version

bundle exec gem bump -p -t
bundle exec gem release

For more options please see gem-release README

Contributing

If you'd like to contribute, please take a look at the instructions for installing dependencies and crafting a good pull request.