spree_loyalty 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d15acfb30891827b6a98ad18bdf142a27719d9788723c6d16d355874b8e5a31f
+  data.tar.gz: c5a3add030ba18043fe115f06590de368765f96afb8565c5e625b2a6ceb7b04a
+SHA512:
+  metadata.gz: 6d7cb518d47c367dfb39561866b2919ed8c9d14e3c4cd6dcad8ea8add75ecba7a261b3516ba2a1a17953988b49b4312aab48b34f75fe0b463b4d6e9864a8a456
+  data.tar.gz: 2447f287e26f39a7907596558aa8ed178ecbc36f0a620857a710d99d8b1519eb16fdd59d63ca2a350ae69ed1f998683ced71ff56d4a8c39d345add8617c224da

data/.gem_release.yml

@@ -0,0 +1,2 @@
+bump:
+  file: "lib/spree_loyalty/version.rb"

data/.github/workflows/test.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/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## 0.1.0
+
+- First release: points-based loyalty program for Spree Commerce, POS-agnostic by design.
+- Accrual on `order.completed` for logged-in customers, based on `item_total` (not the order
+  total — delivery fees excluded).
+- Redemption grants real `Spree::StoreCredit`, spendable through the store's existing Store
+  Credit payment method — no new checkout code.
+- Full ledger (`SpreeLoyalty::Transaction`), not just a running balance.
+- Admin: read-only Loyalty Accounts / Loyalty Transactions pages, plus a manual points-adjustment
+  action for service recovery.
+- Small Store API surface (`GET`/`POST /api/v3/store/loyalty_account`) for storefront
+  integration — verified end to end against a real Next.js storefront (balance display,
+  redemption form, order-confirmation earn message).
+- Fixed a real bug found during that end-to-end verification: `Spree::StoreCredit#amount` is a
+  decimal column, serialized as a JSON string over the API, not a number — the storefront
+  reference implementation's naive `.toFixed()` call crashed on it despite the redemption having
+  already succeeded server-side. Fixed by coercing with `Number(...)` before formatting.

data/CONTRIBUTING.md

@@ -0,0 +1,20 @@
+# Contributing
+
+Thanks for considering a contribution to `spree_loyalty`.
+
+## 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.

data/Gemfile

@@ -0,0 +1,27 @@
+source 'https://rubygems.org'
+
+gem 'rails-controller-testing'
+
+# Pinned to the released 5.6.x line (matching spree_host), same rationale as
+# spree_square/spree_doordash/spree_menu_chat's identical Gemfile comment.
+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,115 @@
+# Spree Loyalty
+
+[![Gem Version](https://img.shields.io/gem/v/spree_loyalty.svg)](https://rubygems.org/gems/spree_loyalty)
+[![GitHub Release](https://img.shields.io/github/v/release/amitkssolanki/spree_loyalty)](https://github.com/amitkssolanki/spree_loyalty/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
+
+A POS-agnostic points loyalty program for [Spree Commerce](https://spreecommerce.org), an open
+source e-commerce platform built with Ruby on Rails. Customers earn points on completed orders
+and redeem them for real `Spree::StoreCredit` — spendable immediately through the store's
+existing Store Credit payment method, with no new checkout/payment code required.
+
+## Why POS-agnostic?
+
+Most restaurant/retail loyalty platforms (Punchh, Square Loyalty, and similar) issue points as a
+program tied to one POS or one brand — a point earned under one system generally isn't
+redeemable under another, even across brands owned by the same company (Yum! Brands keeps Taco
+Bell Rewards, KFC's program, and Pizza Hut Rewards entirely separate, for example). This
+extension takes the opposite approach on purpose: loyalty lives entirely in Spree, independent of
+whatever payment gateway or point-of-sale system a store also happens to use.
+
+## What this does
+
+- **Points accrue automatically on order completion** — `SpreeLoyalty::OrderCompletedSubscriber`
+  reacts to Spree's own `order.completed` event; no coupling to any specific payment or POS
+  integration.
+- **Only logged-in customers earn points.** Guest checkouts don't accrue — loyalty requires an
+  account, the same way most real loyalty programs identify a customer.
+- **Points earn on `item_total`, not the order total** — delivery/shipping fees are excluded from
+  the earn calculation by design.
+- **Redemption grants real `Spree::StoreCredit`**, not a bespoke discount/coupon mechanism —
+  reuses Spree's own mature, already-checkout-integrated store credit system instead of building
+  a parallel one.
+- **A full ledger**, not just a running balance — every earn, redemption, and manual adjustment is
+  a `SpreeLoyalty::Transaction` row, so a balance is always reconstructable and auditable.
+- **Admin visibility** — read-only Loyalty Accounts and Loyalty Transactions pages, plus a manual
+  points-adjustment action for service recovery (comping or correcting a balance).
+- **A small Store API surface** for the storefront — `GET /api/v3/store/loyalty_account` and
+  `POST /api/v3/store/loyalty_account/redeem`, authenticated the same way any other customer
+  Store API endpoint is.
+
+## Installation
+
+1. Add this extension to your Gemfile with this line:
+
+    ```ruby
+    bundle add spree_loyalty
+    ```
+
+2. Run the install generator
+
+    ```ruby
+    bundle exec rails g spree_loyalty:install
+    ```
+
+3. Restart your server
+
+  If your server was running, restart it so that it can find the assets properly.
+
+## Configuration
+
+`SpreeLoyalty::Config` (a `Spree::Preferences::Configuration`, settable the usual Spree way —
+e.g. in a `config/initializers/spree.rb` block):
+
+| Preference | Default | Meaning |
+|---|---|---|
+| `points_per_dollar` | `1` | Points earned per whole dollar of `order.item_total`. |
+| `point_value_cents` | `1` | Cents of store credit granted per point redeemed (default: 100 points = $1.00). |
+| `minimum_redemption_points` | `100` | Smallest redemption a customer can make in one request. |
+
+```ruby
+SpreeLoyalty::Config.points_per_dollar = 2
+SpreeLoyalty::Config.minimum_redemption_points = 50
+```
+
+## How redemption reaches checkout
+
+Redeeming points calls `Spree::StoreCredit.create!(user:, store:, amount:, category: "Loyalty
+Rewards", ...)` directly — the same model Spree's own gift card system uses. The store's existing
+`Spree::PaymentMethod::StoreCredit` payment method (present in any standard Spree install) then
+picks it up automatically at checkout. No new payment gateway, no new checkout step, no
+storefront changes beyond a page to let the customer trigger the redemption.
+
+## Storefront integration
+
+The two Store API endpoints this extension adds are enough to build a full "My Rewards" account
+page: fetch the balance/config with a `GET`, submit a redemption with a `POST`. See this
+extension's own reference implementation in the companion `spree_storefront_web` Next.js app
+(`/account/rewards`) for the full pattern — a balance display, a redemption form, and an
+order-confirmation "You earned N points on this order!" message computed from `item_total *
+points_per_dollar` (client-side, using the same math the real accrual runs server-side, since the
+subscriber that actually credits the account runs asynchronously and may not have finished by the
+time the confirmation page renders).
+
+## Data model
+
+- `SpreeLoyalty::Account` — one per `[user, store]`, `points_balance` and
+  `lifetime_points_earned`.
+- `SpreeLoyalty::Transaction` — the ledger. `kind` is `earned`, `redeemed`, or `adjusted`; `source`
+  is a polymorphic reference to the originating `Spree::Order` (earn) or `Spree::StoreCredit`
+  (redemption), `nil` for a manual admin adjustment.
+
+## 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_loyalty'
+  Rake::Task['extension:test_app'].execute(
+    install_admin: true
+  )
+end

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

@@ -0,0 +1,36 @@
+module Spree
+  module Admin
+    # Read-only support/diagnostic view — no create/edit/destroy for the
+    # account itself (see config/routes.rb: only: [:index]). The one real
+    # write action is #adjust_points, a deliberately narrow escape hatch
+    # for staff comping/correcting a balance, kept separate from normal
+    # CRUD so it always goes through SpreeLoyalty::Redemption-adjacent
+    # ledger bookkeeping rather than a raw balance edit.
+    class LoyaltyAccountsController < ResourceController
+      def model_class
+        SpreeLoyalty::Account
+      end
+
+      def adjust_points
+        account = SpreeLoyalty::Account.find(params[:account_id])
+        points = params[:points].to_i
+        note = params[:note].presence
+
+        if points.zero?
+          flash[:error] = 'Enter a non-zero number of points to adjust.'
+        else
+          SpreeLoyalty::Account.transaction do
+            account.transactions.create!(points: points, kind: SpreeLoyalty::Transaction::ADJUSTED, note: note)
+            account.update!(
+              points_balance: account.points_balance + points,
+              lifetime_points_earned: account.lifetime_points_earned + [points, 0].max
+            )
+          end
+          flash[:success] = "Adjusted #{account.user.email}'s balance by #{points} points."
+        end
+
+        redirect_to admin_loyalty_accounts_path
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Spree
+  module Admin
+    # Read-only ledger view — the audit trail behind every account's
+    # balance. No create/edit/destroy (config/routes.rb: only: [:index]);
+    # adjustments are made via LoyaltyAccountsController#adjust_points,
+    # which itself only ever creates rows here, never edits or removes one.
+    class LoyaltyTransactionsController < ResourceController
+      def model_class
+        SpreeLoyalty::Transaction
+      end
+    end
+  end
+end

data/app/controllers/spree_loyalty/loyalty_account_controller.rb

@@ -0,0 +1,45 @@
+module SpreeLoyalty
+  # Small custom Store API surface (mirrors Spree::Api::V3::Store::WishlistsController's
+  # own require_authentication!/current_user shape — a loyalty account is a
+  # user-scoped resource the same way a wishlist is). The storefront never
+  # touches SpreeLoyalty::Account/Transaction directly, only through these
+  # two actions.
+  class LoyaltyAccountController < Spree::Api::V3::Store::BaseController
+    prepend_before_action :require_authentication!
+
+    # GET /api/v3/store/loyalty_account
+    def show
+      account = find_or_initialize_account
+      render json: account_json(account)
+    end
+
+    # POST /api/v3/store/loyalty_account/redeem
+    def redeem
+      account = find_or_initialize_account
+      account.save! if account.new_record?
+
+      store_credit = SpreeLoyalty::Redemption.call(account: account, points: params[:points])
+      render json: account_json(account.reload).merge(
+        store_credit: { amount: store_credit.amount, currency: store_credit.currency }
+      )
+    rescue SpreeLoyalty::Redemption::Error => e
+      render json: { error: e.message }, status: :unprocessable_entity
+    end
+
+    private
+
+    def find_or_initialize_account
+      SpreeLoyalty::Account.find_or_initialize_by(user: current_user, store: current_store)
+    end
+
+    def account_json(account)
+      {
+        points_balance: account.points_balance,
+        lifetime_points_earned: account.lifetime_points_earned,
+        minimum_redemption_points: SpreeLoyalty::Config.minimum_redemption_points,
+        point_value_cents: SpreeLoyalty::Config.point_value_cents,
+        points_per_dollar: SpreeLoyalty::Config.points_per_dollar
+      }
+    end
+  end
+end

data/app/models/spree_loyalty/account.rb

@@ -0,0 +1,13 @@
+module SpreeLoyalty
+  class Account < Spree.base_class
+    self.table_name = 'spree_loyalty_accounts'
+
+    belongs_to :user, class_name: "::#{Spree.user_class}"
+    belongs_to :store, class_name: 'Spree::Store'
+
+    has_many :transactions, class_name: 'SpreeLoyalty::Transaction', foreign_key: :account_id, dependent: :destroy
+
+    validates :user_id, uniqueness: { scope: :store_id }
+    validates :points_balance, :lifetime_points_earned, numericality: { greater_than_or_equal_to: 0 }
+  end
+end

data/app/models/spree_loyalty/transaction.rb

@@ -0,0 +1,41 @@
+module SpreeLoyalty
+  class Transaction < Spree.base_class
+    self.table_name = 'spree_loyalty_transactions'
+
+    EARNED = 'earned'.freeze
+    REDEEMED = 'redeemed'.freeze
+    ADJUSTED = 'adjusted'.freeze
+    KINDS = [EARNED, REDEEMED, ADJUSTED].freeze
+
+    belongs_to :account, class_name: 'SpreeLoyalty::Account'
+    belongs_to :source, polymorphic: true, optional: true
+
+    validates :kind, inclusion: { in: KINDS }
+    validates :points, numericality: { other_than: 0 }
+    validate :earned_points_are_positive
+    validate :redeemed_or_adjusted_points_are_negative_or_positive_appropriately
+
+    scope :earned, -> { where(kind: EARNED) }
+    scope :redeemed, -> { where(kind: REDEEMED) }
+    scope :adjusted, -> { where(kind: ADJUSTED) }
+
+    private
+
+    def earned_points_are_positive
+      return unless kind == EARNED
+      return if points.to_i.positive?
+
+      errors.add(:points, 'must be positive for an earned transaction')
+    end
+
+    # Redemptions are always a deduction (negative); manual adjustments can
+    # go either way (a comp is positive, a correction can be negative), so
+    # only the sign of a redemption is actually constrained here.
+    def redeemed_or_adjusted_points_are_negative_or_positive_appropriately
+      return unless kind == REDEEMED
+      return if points.to_i.negative?
+
+      errors.add(:points, 'must be negative for a redeemed transaction')
+    end
+  end
+end

data/app/services/spree_loyalty/accrual.rb

@@ -0,0 +1,38 @@
+module SpreeLoyalty
+  # Awards loyalty points for a completed order. Guest checkouts (no
+  # order.user) don't earn — loyalty requires an account, same reasoning
+  # Square Loyalty itself uses (it identifies customers by phone number to
+  # accrue points; an anonymous sale earns nothing there either). No
+  # retroactive guest-to-account linking in this version — a guest who
+  # creates an account later doesn't get past orders' points backfilled.
+  #
+  # Points accrue on order.item_total, not order.total — a restaurant
+  # loyalty program crediting points for the DoorDash delivery fee would be
+  # an unstated, arguably wrong default; this makes the choice explicit.
+  class Accrual
+    def self.call(...) = new.call(...)
+
+    def call(order)
+      return if order.user.blank?
+
+      points = (order.item_total * SpreeLoyalty::Config.points_per_dollar).floor
+      return unless points.positive?
+
+      account = SpreeLoyalty::Account.find_or_create_by!(user: order.user, store: order.store)
+
+      SpreeLoyalty::Account.transaction do
+        account.transactions.create!(
+          points: points,
+          kind: SpreeLoyalty::Transaction::EARNED,
+          source: order
+        )
+        account.update!(
+          points_balance: account.points_balance + points,
+          lifetime_points_earned: account.lifetime_points_earned + points
+        )
+      end
+
+      account
+    end
+  end
+end

data/app/services/spree_loyalty/redemption.rb

@@ -0,0 +1,61 @@
+module SpreeLoyalty
+  # Converts points into a real Spree::StoreCredit grant, spendable
+  # immediately through the store's existing Store Credit payment method —
+  # deliberately no bespoke discount/coupon engine. Returns the created
+  # Spree::StoreCredit on success; raises SpreeLoyalty::Redemption::Error
+  # (with a message meant to be shown to the customer) on failure.
+  class Redemption
+    class Error < StandardError; end
+
+    # Lazily created once per store on first redemption, not seeded — a
+    # store that never runs loyalty never gets an unused category cluttering
+    # its Store Credit admin.
+    CATEGORY_NAME = 'Loyalty Rewards'.freeze
+
+    def self.call(...) = new.call(...)
+
+    def call(account:, points:)
+      points = points.to_i
+      validate!(account, points)
+
+      dollars = points_to_dollars(points)
+
+      SpreeLoyalty::Account.transaction do
+        store_credit = Spree::StoreCredit.create!(
+          user: account.user,
+          store: account.store,
+          amount: dollars,
+          currency: account.store.default_currency,
+          category: loyalty_category,
+          memo: "Redeemed #{points} loyalty points"
+        )
+        account.transactions.create!(
+          points: -points,
+          kind: SpreeLoyalty::Transaction::REDEEMED,
+          source: store_credit
+        )
+        account.update!(points_balance: account.points_balance - points)
+
+        store_credit
+      end
+    end
+
+    private
+
+    def validate!(account, points)
+      minimum = SpreeLoyalty::Config.minimum_redemption_points
+
+      raise Error, 'Enter a number of points to redeem' unless points.positive?
+      raise Error, "You need at least #{minimum} points to redeem" if points < minimum
+      raise Error, "You only have #{account.points_balance} points" if points > account.points_balance
+    end
+
+    def points_to_dollars(points)
+      (points * SpreeLoyalty::Config.point_value_cents) / 100.0
+    end
+
+    def loyalty_category
+      Spree::StoreCreditCategory.find_or_create_by!(name: CATEGORY_NAME)
+    end
+  end
+end

data/app/subscribers/spree_loyalty/order_completed_subscriber.rb

@@ -0,0 +1,19 @@
+module SpreeLoyalty
+  # Events & Subscribers is the preferred pattern for this kind of side
+  # effect (per this app's own CLAUDE.md conventions) — react to
+  # order.completed without touching Spree::Order itself. Mirrors
+  # SpreeSquare::OrderCompletedSubscriber / SpreeDoordash's own subscriber
+  # shape exactly; fully independent of both — Spree's Events system fires
+  # every subscriber for the same event, confirmed live this session
+  # watching all three fire for the same real order.
+  class OrderCompletedSubscriber < Spree::Subscriber
+    subscribes_to 'order.completed'
+
+    def handle(event)
+      order = Spree::Order.find_by_prefix_id(event.payload['id'])
+      return unless order
+
+      SpreeLoyalty::Accrual.call(order)
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+<% content_for :page_title do %>
+  Loyalty Accounts
+<% end %>
+
+<%= render_table @collection, :loyalty_accounts %>
+
+<div class="card mt-3">
+  <div class="card-header">
+    <h5 class="mb-0">Adjust a balance</h5>
+  </div>
+  <div class="card-body">
+    <p class="text-muted">
+      Comp or correct a customer's points balance (e.g. service recovery). Positive numbers add
+      points, negative numbers deduct — both are logged in Loyalty Transactions as an
+      <code>adjusted</code> entry.
+    </p>
+    <%= form_tag spree.adjust_points_admin_loyalty_accounts_path, method: :post do %>
+      <div class="row g-2 align-items-end">
+        <div class="col-auto">
+          <%= label_tag :account_id, 'Account ID' %>
+          <%= number_field_tag :account_id, nil, class: 'form-control', required: true %>
+        </div>
+        <div class="col-auto">
+          <%= label_tag :points, 'Points (+/-)' %>
+          <%= number_field_tag :points, nil, class: 'form-control', required: true %>
+        </div>
+        <div class="col-auto">
+          <%= label_tag :note, 'Note' %>
+          <%= text_field_tag :note, nil, class: 'form-control' %>
+        </div>
+        <div class="col-auto">
+          <%= button_tag 'Adjust', type: :submit, class: 'btn btn-primary' %>
+        </div>
+      </div>
+    <% end %>
+  </div>
+</div>

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

@@ -0,0 +1,5 @@
+<% content_for :page_title do %>
+  Loyalty Transactions
+<% end %>
+
+<%= render_table @collection, :loyalty_transactions %>

data/config/initializers/spree.rb

@@ -0,0 +1,15 @@
+# Registers this extension's event subscriber with Spree's event system.
+#
+# Spree::Subscriber's own docstring says subscribers are "automatically
+# registered during Rails initialization" — that's not what actually
+# happens in spree_core 5.6.1: Spree::Events.register_subscribers! only
+# ever iterates the explicit Spree.subscribers array (see
+# spree_core/lib/spree/events.rb), there is no Zeitwerk-descendant scan.
+# Without this file, SpreeLoyalty::OrderCompletedSubscriber is a real,
+# loadable class but never actually wired to the 'order.completed' event —
+# spree_square and spree_doordash both hit this live before adding their
+# own identical registration file; mirroring it here from the start rather
+# than rediscovering the same bug a third time.
+Rails.application.config.after_initialize do
+  Spree.subscribers << SpreeLoyalty::OrderCompletedSubscriber
+end

data/config/initializers/spree_admin_loyalty_navigation.rb

@@ -0,0 +1,20 @@
+Rails.application.config.after_initialize do
+  # Positions 73-74 — right after spree_menu_chat's own entries (71-72), so
+  # every extension's nav items sit together without colliding. (spree_square:
+  # 65-67, spree_doordash: 68-70, spree_menu_chat: 71-72.)
+  Spree.admin.navigation.sidebar.add :loyalty_accounts,
+    label: 'Loyalty Accounts',
+    url: :admin_loyalty_accounts_path,
+    icon: 'award',
+    position: 73,
+    active: -> { controller_name == 'loyalty_accounts' },
+    if: -> { can?(:manage, SpreeLoyalty::Account) }
+
+  Spree.admin.navigation.sidebar.add :loyalty_transactions,
+    label: 'Loyalty Transactions',
+    url: :admin_loyalty_transactions_path,
+    icon: 'list-details',
+    position: 74,
+    active: -> { controller_name == 'loyalty_transactions' },
+    if: -> { can?(:manage, SpreeLoyalty::Transaction) }
+end

data/config/initializers/spree_admin_loyalty_tables.rb

@@ -0,0 +1,96 @@
+Rails.application.config.after_initialize do
+  # new_resource: false — read-only support/diagnostic tables (no
+  # `:new`/`:create` route; only: [:index] in config/routes.rb). Without
+  # this the empty-state partial builds a `new_object_url` link
+  # unconditionally and 500s the moment the table is ever empty — the exact
+  # bug spree_square and spree_doordash each hit live on their first real
+  # Postgres run and fixed in their own spree_admin_*_tables.rb. Copying
+  # their already-fixed pattern here instead of rediscovering it a third
+  # time.
+  Spree.admin.tables.register(:loyalty_accounts, model_class: SpreeLoyalty::Account,
+                                                   search_param: :user_email_cont, new_resource: false)
+
+  Spree.admin.tables.loyalty_accounts.add :id,
+    label: :id,
+    type: :string,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 5
+
+  Spree.admin.tables.loyalty_accounts.add :user_email,
+    label: :customer,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 10,
+    method: ->(account) { account.user&.email }
+
+  Spree.admin.tables.loyalty_accounts.add :points_balance,
+    label: :points_balance,
+    type: :string,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 20
+
+  Spree.admin.tables.loyalty_accounts.add :lifetime_points_earned,
+    label: :lifetime_points_earned,
+    type: :string,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 30
+
+  Spree.admin.tables.loyalty_accounts.add :created_at,
+    label: :member_since,
+    type: :datetime,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 40
+
+  Spree.admin.tables.register(:loyalty_transactions, model_class: SpreeLoyalty::Transaction,
+                                                       search_param: :kind_cont, new_resource: false)
+
+  Spree.admin.tables.loyalty_transactions.add :account_id,
+    label: :account_id,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 10
+
+  Spree.admin.tables.loyalty_transactions.add :kind,
+    label: :kind,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 20
+
+  Spree.admin.tables.loyalty_transactions.add :points,
+    label: :points,
+    type: :string,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 30
+
+  Spree.admin.tables.loyalty_transactions.add :note,
+    label: :note,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 40
+
+  Spree.admin.tables.loyalty_transactions.add :created_at,
+    label: :created_at,
+    type: :datetime,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 50
+end

data/config/locales/en.yml

@@ -0,0 +1,5 @@
+en:
+  spree_loyalty:
+    account_id: "Account ID"
+    points: "Points"
+    adjust: "Adjust"

data/config/routes.rb

@@ -0,0 +1,23 @@
+Spree::Core::Engine.add_routes do
+  namespace :admin do
+    resources :loyalty_accounts, only: [:index] do
+      collection do
+        post :adjust_points
+      end
+    end
+    resources :loyalty_transactions, only: [:index]
+  end
+
+  # Small custom Store API surface (same "extend spree_api with just what
+  # the storefront needs" pattern spree_square already uses for modifier
+  # lists) — the storefront never touches SpreeLoyalty::Account/Transaction
+  # directly, only through these two endpoints.
+  namespace :api, defaults: { format: 'json' } do
+    namespace :v3 do
+      namespace :store do
+        get 'loyalty_account', to: '/spree_loyalty/loyalty_account#show'
+        post 'loyalty_account/redeem', to: '/spree_loyalty/loyalty_account#redeem'
+      end
+    end
+  end
+end

data/db/migrate/20260820000001_create_spree_loyalty_accounts.rb

@@ -0,0 +1,18 @@
+class CreateSpreeLoyaltyAccounts < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_loyalty_accounts do |t|
+      t.references :user, null: false, foreign_key: { to_table: Spree.user_class.table_name }
+      t.references :store, null: false, foreign_key: { to_table: :spree_stores }
+
+      t.integer :points_balance, null: false, default: 0
+      t.integer :lifetime_points_earned, null: false, default: 0
+
+      t.timestamps
+    end
+
+    # One account per user per store — accrual/redemption both
+    # find_or_create_by! on [user, store], so this is the constraint that
+    # actually keeps that safe under concurrent requests.
+    add_index :spree_loyalty_accounts, %i[user_id store_id], unique: true
+  end
+end

data/db/migrate/20260820000002_create_spree_loyalty_transactions.rb

@@ -0,0 +1,38 @@
+class CreateSpreeLoyaltyTransactions < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_loyalty_transactions do |t|
+      t.references :account, null: false, foreign_key: { to_table: :spree_loyalty_accounts }
+
+      # Signed — positive for an earn, negative for a redemption or a
+      # manual deduction. The running Account#points_balance is a cache of
+      # summing this column; this table is the real source of truth (same
+      # "keep a real audit trail, don't just mutate a running total"
+      # precedent as SpreeSquare::WebhookEvent/OrderMapping).
+      t.integer :points, null: false
+
+      # 'earned' | 'redeemed' | 'adjusted' — a plain string, not a Rails
+      # enum backed by an integer column: this table is read directly in
+      # the admin ledger view and in support queries, and a string reads
+      # there without a lookup table, same rationale already used for
+      # SpreeSquare::OrderMapping#last_status and
+      # SpreeDoordash::DeliveryMapping#last_status.
+      t.string :kind, null: false
+
+      # Polymorphic source of the transaction — Spree::Order for a real
+      # earn event, nil for a manual admin adjustment (kind: 'adjusted').
+      # Redemptions ('redeemed') point at the Spree::StoreCredit they
+      # granted, so the ledger and the spendable balance are directly
+      # traceable to each other.
+      t.references :source, polymorphic: true, null: true
+
+      # Free-text note — populated for admin-initiated adjustments (why a
+      # staff member comped points), blank for order-driven earn/redeem
+      # rows where the source association already explains itself.
+      t.text :note
+
+      t.timestamps
+    end
+
+    add_index :spree_loyalty_transactions, :kind
+  end
+end

data/lib/generators/spree_loyalty/install/install_generator.rb

@@ -0,0 +1,20 @@
+module SpreeLoyalty
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      class_option :migrate, type: :boolean, default: true
+
+      def add_migrations
+        run 'bundle exec rake railties:install:migrations FROM=spree_loyalty'
+      end
+
+      def run_migrations
+        run_migrations = options[:migrate] || ['', 'y', 'Y'].include?(ask('Would you like to run the migrations now? [Y/n]'))
+        if run_migrations
+          run 'bin/rails db:migrate'
+        else
+          puts 'Skipping rails db:migrate, don\'t forget to run it!'
+        end
+      end
+    end
+  end
+end

data/lib/spree_loyalty/configuration.rb

@@ -0,0 +1,19 @@
+module SpreeLoyalty
+  class Configuration < Spree::Preferences::Configuration
+    # Points earned per whole dollar of an order's item_total (delivery
+    # fees excluded — see Accrual for why order.item_total, not
+    # order.total). 1 point per $1 is the plain, easy-to-explain default;
+    # store owners tune it from here without a code change.
+    preference :points_per_dollar, :integer, default: 1
+
+    # Cents of Spree::StoreCredit granted per point redeemed. Default
+    # 1 -> 100 points = $1.00, i.e. the same 1-point-per-cent-of-a-dollar
+    # rate as the earn side, so "100 points" reads the same as "$1" in both
+    # directions without the store owner having to do math.
+    preference :point_value_cents, :integer, default: 1
+
+    # Floor on a single redemption — prevents a $0.01 store-credit grant
+    # (and the matching tiny StoreCredit row) for a 1-point redemption.
+    preference :minimum_redemption_points, :integer, default: 100
+  end
+end

data/lib/spree_loyalty/engine.rb

@@ -0,0 +1,34 @@
+module SpreeLoyalty
+  class Engine < Rails::Engine
+    require 'spree/core'
+    isolate_namespace Spree
+    engine_name 'spree_loyalty'
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    initializer 'spree_loyalty.environment', before: :load_config_initializers do |_app|
+      SpreeLoyalty::Config = SpreeLoyalty::Configuration.new
+    end
+
+    # No external API, no encrypted credentials — unlike spree_square/
+    # spree_doordash this extension never talks outbound, so it has no
+    # equivalent of their ACTIVE_RECORD_ENCRYPTION_* initializer to run
+    # before Active Record's own encryption-configuration initializer.
+
+    # Force-loads decorator files the same way spree_square/spree_doordash's
+    # engines do — Zeitwerk's lazy autoloading never triggers a decorator
+    # file's `prepend` line on its own (nothing references the exact
+    # `Spree::XyzDecorator` constant name), so each engine has to eager-load
+    # its own app/ tree explicitly. See spree_square/lib/spree_square/engine.rb
+    # for the full rationale.
+    def self.activate
+      Dir.glob(File.join(File.dirname(__FILE__), '../../app/**/*_decorator*.rb')) do |c|
+        Rails.application.config.cache_classes ? require(c) : load(c)
+      end
+    end
+
+    config.to_prepare(&method(:activate).to_proc)
+  end
+end

data/lib/spree_loyalty/factories.rb

@@ -0,0 +1,14 @@
+FactoryBot.define do
+  factory :loyalty_account, class: 'SpreeLoyalty::Account' do
+    user
+    store
+    points_balance { 0 }
+    lifetime_points_earned { 0 }
+  end
+
+  factory :loyalty_transaction, class: 'SpreeLoyalty::Transaction' do
+    association :account, factory: :loyalty_account
+    points { 10 }
+    kind { SpreeLoyalty::Transaction::EARNED }
+  end
+end

data/lib/spree_loyalty/version.rb

@@ -0,0 +1,7 @@
+module SpreeLoyalty
+  VERSION = '0.1.0'.freeze
+
+  def gem_version
+    Gem::Version.new(VERSION)
+  end
+end

data/lib/spree_loyalty.rb

@@ -0,0 +1,12 @@
+require 'spree'
+require 'spree_loyalty/engine'
+require 'spree_loyalty/version'
+require 'spree_loyalty/configuration'
+
+module SpreeLoyalty
+  mattr_accessor :queue
+
+  def self.queue
+    @@queue ||= Spree.queues.default
+  end
+end

data/spree_loyalty.gemspec

@@ -0,0 +1,42 @@
+# encoding: UTF-8
+lib = File.expand_path('../lib/', __FILE__)
+$LOAD_PATH.unshift lib unless $LOAD_PATH.include?(lib)
+
+require 'spree_loyalty/version'
+
+Gem::Specification.new do |s|
+  s.platform    = Gem::Platform::RUBY
+  s.name        = 'spree_loyalty'
+  s.version     = SpreeLoyalty::VERSION
+  s.summary     = 'Spree Commerce Points-Based Loyalty Program'
+  s.description = 'A POS-agnostic points loyalty program for Spree Commerce: customers earn points ' \
+                   'on completed orders and redeem them for real Spree::StoreCredit, spendable through ' \
+                   'the store\'s existing Store Credit payment method — no new checkout code needed. ' \
+                   'Independent of any point-of-sale or payment provider.'
+  s.required_ruby_version = '>= 3.2'
+
+  s.author    = 'Amit Solanki'
+  s.email     = 'amitkssolanki@gmail.com'
+  s.homepage  = 'https://github.com/amitkssolanki/spree_loyalty'
+  s.license   = 'MIT'
+
+  s.metadata = {
+    'homepage_uri' => s.homepage,
+    'source_code_uri' => s.homepage,
+    'changelog_uri' => "#{s.homepage}/blob/main/CHANGELOG.md",
+    'bug_tracker_uri' => "#{s.homepage}/issues"
+  }
+
+  s.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.start_with?('spec/') && !f.start_with?('spec/fixtures')
+  end
+  s.require_path = 'lib'
+  s.requirements << 'none'
+
+  spree_version = '>= 5.4.0.beta'
+  s.add_dependency 'spree', spree_version
+  s.add_dependency 'spree_admin', spree_version
+
+  s.add_development_dependency 'spree_dev_tools'
+  s.add_development_dependency 'gem-release'
+end

metadata

@@ -0,0 +1,137 @@
+--- !ruby/object:Gem::Specification
+name: spree_loyalty
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Amit Solanki
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: spree
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.4.0.beta
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.4.0.beta
+- !ruby/object:Gem::Dependency
+  name: spree_admin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.4.0.beta
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.4.0.beta
+- !ruby/object:Gem::Dependency
+  name: spree_dev_tools
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: gem-release
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 'A POS-agnostic points loyalty program for Spree Commerce: customers
+  earn points on completed orders and redeem them for real Spree::StoreCredit, spendable
+  through the store''s existing Store Credit payment method — no new checkout code
+  needed. Independent of any point-of-sale or payment provider.'
+email: amitkssolanki@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gem_release.yml"
+- ".github/workflows/test.yml"
+- ".gitignore"
+- ".rspec"
+- CHANGELOG.md
+- CONTRIBUTING.md
+- Gemfile
+- LICENSE.md
+- README.md
+- Rakefile
+- app/controllers/spree/admin/loyalty_accounts_controller.rb
+- app/controllers/spree/admin/loyalty_transactions_controller.rb
+- app/controllers/spree_loyalty/loyalty_account_controller.rb
+- app/models/spree_loyalty/account.rb
+- app/models/spree_loyalty/transaction.rb
+- app/services/spree_loyalty/accrual.rb
+- app/services/spree_loyalty/redemption.rb
+- app/subscribers/spree_loyalty/order_completed_subscriber.rb
+- app/views/spree/admin/loyalty_accounts/index.html.erb
+- app/views/spree/admin/loyalty_transactions/index.html.erb
+- config/initializers/spree.rb
+- config/initializers/spree_admin_loyalty_navigation.rb
+- config/initializers/spree_admin_loyalty_tables.rb
+- config/locales/en.yml
+- config/routes.rb
+- db/migrate/20260820000001_create_spree_loyalty_accounts.rb
+- db/migrate/20260820000002_create_spree_loyalty_transactions.rb
+- lib/generators/spree_loyalty/install/install_generator.rb
+- lib/spree_loyalty.rb
+- lib/spree_loyalty/configuration.rb
+- lib/spree_loyalty/engine.rb
+- lib/spree_loyalty/factories.rb
+- lib/spree_loyalty/version.rb
+- spree_loyalty.gemspec
+homepage: https://github.com/amitkssolanki/spree_loyalty
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/amitkssolanki/spree_loyalty
+  source_code_uri: https://github.com/amitkssolanki/spree_loyalty
+  changelog_uri: https://github.com/amitkssolanki/spree_loyalty/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/amitkssolanki/spree_loyalty/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements:
+- none
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Spree Commerce Points-Based Loyalty Program
+test_files: []