spree_boxnow 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2900ebc580d24fc4b70391b12db03014aa48254a0d412350080705e29f72d690
+  data.tar.gz: 1abfd9b5be518d7f399712aa903ad429c5506243a5c2276e22d1f1f4ec58b725
+SHA512:
+  metadata.gz: a4326bb2f22ce5ad3864e72ba7ae3b616a3418ddf73f26252a1821b1adc531d38b7a8a61c1768f1f60ce5b848cee062814dd5465d07451821fe4b43aaef41d81
+  data.tar.gz: edb9c3871bf6237ee19111de09a48d18d4fdc2a437ffd7140ee2a02f0f1adf01875dc7f36aacd49e6535e023b0593808982fd015b2855c87f9ae76548623f473

data/README.md

@@ -0,0 +1,225 @@
+# spree_boxnow
+
+A [Spree Commerce](https://spreecommerce.org) extension that integrates **BoxNow** locker delivery (APM — Automatic Parcel Machine) for Greek e-commerce stores. BoxNow is a last-mile carrier operating exclusively in Greece.
+
+[![Gem Version](https://badge.fury.io/rb/spree_boxnow.svg)](https://badge.fury.io/rb/spree_boxnow)
+
+## Installation
+
+1. Add to your Gemfile:
+
+   ```bash
+   bundle add spree_boxnow
+   ```
+
+2. Run the install generator (copies migrations, mounts routes):
+
+   ```bash
+   bundle exec rails g spree_boxnow:install
+   ```
+
+   The generator will ask whether to run `db:migrate` immediately. If you skip it:
+
+   ```bash
+   bin/rails db:migrate
+   ```
+
+3. Restart your server.
+
+---
+
+## Setup
+
+### 1. Configure BoxNow credentials
+
+Go to **Admin → Integrations → BoxNow** and fill in:
+
+| Field | Description |
+|-------|-------------|
+| **Client ID** | Provided by BoxNow |
+| **Client Secret** | Provided by BoxNow |
+| **Partner ID** | Provided by BoxNow |
+| **API URL** | BoxNow API base URL (e.g. `https://api-production.boxnow.gr`) |
+| **Origin Location ID** | Your warehouse/store APM location ID |
+| **Contact Name** | Sender contact name printed on labels |
+| **Contact Phone** | Sender phone number |
+| **Contact Email** | Sender email address |
+
+OAuth2 tokens are obtained automatically using Client Credentials and cached in `Rails.cache` for 1 hour.
+
+### 2. Set product dimensions
+
+The shipping calculator determines the price tier from the physical dimensions of the items in the order. Every **Variant** must have `height`, `width`, and `depth` set in **centimetres**.
+
+- If any variant in the order is missing dimensions, the BoxNow shipping method will **not appear** at checkout.
+- BoxNow supports **one parcel per order** — all items are treated as a single combined package. If the combined package exceeds BoxNow hard limits, the method is hidden.
+
+BoxNow hard limits:
+
+| Dimension | Limit |
+|-----------|-------|
+| Max weight | 20 kg |
+| Max height | 36 cm |
+| Max width | 45 cm |
+| Max depth | 60 cm |
+
+### 3. Create a BoxNow shipping method
+
+Go to **Admin → Shipping Methods → New**:
+
+1. Name it (e.g. "BoxNow Locker Delivery")
+2. Tick the **BoxNow** checkbox so the extension recognises it
+3. Select **BoxNow Rate** as the calculator
+4. Set the calculator preferences:
+
+| Preference | Default | Description |
+|------------|---------|-------------|
+| **Small box price** | 0.0 | Price for parcels ≤ 8 cm in height |
+| **Medium box price** | 0.0 | Price for parcels ≤ 17 cm in height |
+| **Large box price** | 0.0 | Price for parcels ≤ 36 cm in height |
+| **Base padding (cm)** | 1.0 | Added to every dimension to account for the physical box being slightly larger than its contents. Set to `0` to disable. |
+| **Multi-item factor** | 1.05 | Multiplier applied to all dimensions when an order has more than one item (accounts for imperfect stacking). Set to `1.0` to disable. |
+
+---
+
+## How parcel sizing works
+
+The calculator models the entire order as **one parcel** — there is no multi-box splitting.
+
+For each line item it:
+1. Sorts the variant's three dimensions smallest → largest (`s ≤ m ≤ d`)
+2. Stacks items along the smallest axis: `parcel_height += s × quantity`
+3. Takes `width = max(m)` and `depth = max(d)` across all items
+
+After stacking, padding and the multi-item factor are applied. The resulting three dimensions are then sorted again to allow virtual rotation, and the smallest is compared against the tier thresholds.
+
+| Tier | Height threshold |
+|------|-----------------|
+| Small | ≤ 8 cm |
+| Medium | ≤ 17 cm |
+| Large | ≤ 36 cm |
+
+If the package exceeds the large threshold or any hard limit, `nil` is returned and the BoxNow shipping option is hidden from checkout.
+
+---
+
+## Storefront — locker picker
+
+When a customer selects a BoxNow shipping rate at checkout, a locker picker is injected inline. The picker uses the **BoxNow JS widget** which opens a popup map of available APM locations.
+
+On locker selection the widget callback POSTs to `/boxnow/select_locker`, which stores:
+
+- `boxnow.destination_location_id`
+- `boxnow.locker_name`
+- `boxnow.locker_address`
+
+into `shipment.private_metadata`. Once a voucher is created the locker cannot be changed — further calls to `select_locker` are silently ignored for tracked shipments.
+
+---
+
+## Admin — voucher lifecycle
+
+Prerequisites for an order to be eligible:
+
+- Shipping and billing addresses present
+- Payment completed
+- Shipment state: **ready**
+- A BoxNow locker has been selected by the customer at checkout
+
+### Creating a voucher
+
+1. Open the order in **Spree Admin**.
+2. The **"Create Voucher"** option appears in the top-right actions dropdown when the shipment is ready and not yet tracked.
+3. Click it — the extension calls the BoxNow API (`POST /api/v1/delivery-requests`) and stores:
+   - `shipment.tracking` ← primary parcel ID
+   - `shipment.private_metadata['boxnow.vg_child']` ← any child parcel IDs
+
+### Printing a voucher
+
+Once a voucher exists ("Print Voucher" appears in the dropdown):
+
+1. Click **"Print Voucher"** — the extension fetches the PDF label for every parcel ID (primary + children).
+2. Multiple PDFs are merged into one using `combine_pdf`.
+3. The merged PDF is sent inline in a new browser tab, ready to print.
+
+### Cancelling a voucher
+
+The cancel action is available via `POST admin/boxnow/:order_id/cancel` (guard: shipment must be tracked and not yet shipped). When called it:
+
+1. Calls `POST /api/v1/parcels/{id}:cancel` on the BoxNow API
+2. Clears `shipment.tracking` and removes `boxnow.vg_child` from `private_metadata`
+
+> The cancel button in the admin UI is not yet wired up — see [What's not implemented](#whats-not-implemented).
+
+### Retry behaviour
+
+If a voucher creation attempt fails and the admin retries, the extension appends an attempt counter to the order number (`{shipment.number}-2`, `-3`, etc.) to avoid duplicate-order errors from the BoxNow API.
+
+---
+
+## Routes
+
+| Method | Path | Action |
+|--------|------|--------|
+| `POST` | `/boxnow/select_locker` | Storefront: save locker selection |
+| `POST` | `/{admin_path}/boxnow/:order_id/create` | Admin: create voucher |
+| `GET` | `/{admin_path}/boxnow/:order_id/print` | Admin: print/download voucher PDF |
+| `POST` | `/{admin_path}/boxnow/:order_id/cancel` | Admin: cancel voucher |
+| `POST` | `/{admin_path}/boxnow/:order_id/select_locker` | Admin: update locker selection (pre-voucher only) |
+
+---
+
+## What's not implemented
+
+- **Webhook handling** — BoxNow pushes parcel status events to a configurable endpoint. A public route and shipment state updates are not yet implemented. See `docs/BoxNow parcel events webhooks (10-11-23).pdf` for the event payload reference.
+- **Cancel voucher UI** — the `CancelVoucher` service and the admin route exist but there is no button in the order dropdown yet.
+
+---
+
+## Developing
+
+```bash
+# Install dependencies and set up the dummy app (required before first test run)
+bundle install
+bundle exec rake test_app
+
+# Run all specs
+bundle exec rspec
+
+# Run a single spec
+bundle exec rspec spec/feature/home_page_spec.rb
+```
+
+Integration tests require these env vars (load via dotenv or export manually):
+
+```
+BOXNOW_CLIENT_ID=
+BOXNOW_CLIENT_SECRET=
+BOXNOW_PARTNER_ID=
+BOXNOW_API_URL=
+```
+
+When testing a host app's integration you can use the gem's factories:
+
+```ruby
+require 'spree_boxnow/factories'
+```
+
+---
+
+## Releasing a new version
+
+```bash
+bundle exec gem bump -p -t
+bundle exec gem release
+```
+
+See [gem-release README](https://github.com/svenfuchs/gem-release) for more options.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on setting up a development environment and submitting pull requests.
+
+Copyright (c) 2026 OlympusOne, released under the MIT License.

data/Rakefile

@@ -0,0 +1,21 @@
+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_boxnow'
+  Rake::Task['extension:test_app'].invoke
+end

data/app/assets/config/spree_boxnow_manifest.js

@@ -0,0 +1,3 @@
+//= link_tree ../images
+//= link spree_boxnow/application.js
+//= link_tree ../../javascript/spree_boxnow/controllers .js

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

@@ -0,0 +1,126 @@
+require 'combine_pdf'
+
+module Spree
+  module Admin
+    class BoxnowController < Spree::Admin::BaseController
+      include Spree::Admin::OrdersFiltersHelper
+
+      def create
+        begin
+          load_order
+
+          @order.shipments.each do |shipment|
+            next unless shipment.can_create_boxnow_voucher?
+
+            result = SpreeBoxnow::CreateVoucher.new(shipment).call
+
+            shipment.tracking = result[:parcel_id]
+            shipment.private_metadata['boxnow.vg_child'] = result[:child_parcel_ids]
+            shipment.save!
+          end
+
+          flash[:success] = Spree.t('admin.integrations.boxnow.voucher_successfully_created')
+        rescue ActiveRecord::RecordNotFound
+          order_not_found
+        rescue StandardError => e
+          Rails.logger.error "Boxnow Error: #{e.message}"
+
+          flash[:error] = "#{Spree.t('admin.integrations.boxnow.voucher_creation_failed')}: #{e.message}"
+        end
+      end
+
+      def print
+        begin
+          load_order
+
+          shipments = @order.shipments.select(&:can_print_boxnow_voucher?)
+
+          voucher_numbers = shipments.flat_map do |shipment|
+            child_ids = shipment.private_metadata['boxnow.vg_child'] || []
+            [shipment.tracking] + child_ids
+          end
+
+          if voucher_numbers.empty?
+            raise StandardError, Spree.t('admin.integrations.boxnow.voucher_print_failed')
+          end
+
+          pdf_contents = voucher_numbers.map do |parcel_id|
+            SpreeBoxnow::PrintVouchers.new(parcel_id).call
+          end
+
+          merged_bytes =
+            if pdf_contents.size == 1
+              pdf_contents.first
+            else
+              combined = CombinePDF.new
+              pdf_contents.each { |bytes| combined << CombinePDF.parse(bytes) }
+              combined.to_pdf
+            end
+
+          send_data merged_bytes,
+            filename: "#{@order.number}.pdf",
+            type: 'application/pdf',
+            disposition: 'inline'
+        rescue ActiveRecord::RecordNotFound
+          render json: {
+            error: flash_message_for(Spree::Order.new, :not_found)
+          }, status: 404
+        rescue StandardError => e
+          Rails.logger.error "Boxnow Error: #{e.message}"
+
+          render json: {
+            error: Spree.t('admin.integrations.boxnow.voucher_print_failed')
+          }, status: 400
+        end
+      end
+
+      def cancel
+        load_order
+
+        @order.shipments.each do |shipment|
+          next unless shipment.can_cancel_boxnow_voucher?
+
+          SpreeBoxnow::CancelVoucher.new(shipment).call
+        end
+
+        flash[:success] = Spree.t('admin.integrations.boxnow.voucher_successfully_cancelled')
+      rescue ActiveRecord::RecordNotFound
+        order_not_found
+      rescue StandardError => e
+        Rails.logger.error "Boxnow Error: #{e.message}"
+
+        flash[:error] = "#{Spree.t('admin.integrations.boxnow.voucher_cancellation_failed')}: #{e.message}"
+      end
+
+      def select_locker
+        load_order
+        shipment = @order.shipments.find { |s| s.shipping_method&.boxnow? }
+
+        if shipment.nil? || params[:locker_id].blank?
+          render json: { error: 'Invalid request' }, status: :unprocessable_entity and return
+        end
+
+        shipment.private_metadata['boxnow.destination_location_id'] = params[:locker_id]
+        shipment.private_metadata['boxnow.locker_name']             = params[:locker_name]
+        shipment.private_metadata['boxnow.locker_address']          = params[:locker_address]
+        shipment.save!
+
+        render json: { success: true }
+      rescue ActiveRecord::RecordNotFound
+        order_not_found
+      end
+
+      private
+
+      def load_order
+        @order = current_store.orders.find(params[:order_id])
+        authorize! action, @order
+        @order
+      end
+
+      def order_not_found
+        flash[:error] = flash_message_for(Spree::Order.new, :not_found)
+      end
+    end
+  end
+end

data/app/controllers/spree/boxnow_controller.rb

@@ -0,0 +1,24 @@
+module Spree
+  class BoxnowController < Spree::StoreController
+    def select_locker
+      order = current_order
+
+      if order.blank? || params[:locker_id].blank?
+        render json: { error: 'Invalid request' }, status: :unprocessable_entity
+        return
+      end
+
+      order.shipments.each do |shipment|
+        next unless shipment.shipping_method&.boxnow?
+        next if shipment.tracked?
+
+        shipment.private_metadata['boxnow.destination_location_id'] = params[:locker_id]
+        shipment.private_metadata['boxnow.locker_name']             = params[:locker_name]
+        shipment.private_metadata['boxnow.locker_address']          = params[:locker_address]
+        shipment.save!
+      end
+
+      render json: { success: true }
+    end
+  end
+end

data/app/javascript/spree_boxnow/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 SpreeBoxnowController from 'spree_boxnow/controllers/spree_boxnow_controller'
+
+application.register('spree-boxnow', SpreeBoxnowController)

data/app/javascript/spree_boxnow/controllers/spree_boxnow_controller.js

@@ -0,0 +1,34 @@
+import { Controller } from "@hotwired/stimulus";
+import { post } from "@rails/request.js";
+
+export default class extends Controller {
+  static values = {
+    orderId: Number,
+    createVoucherPrompt: String,
+    createVoucherError: String,
+    cancelVoucherPrompt: String,
+    cancelVoucherError: String,
+  };
+
+  async createVoucher(event) {
+    event.preventDefault();
+
+    const value = window.confirm(this.createVoucherPromptValue);
+    if (!value) return;
+
+    await post(`${Spree.adminPath}/boxnow/${this.orderIdValue}/create`);
+
+    Turbo.visit(window.location.href, { action: "replace" });
+  }
+
+  async cancelVoucher(event) {
+    event.preventDefault();
+
+    const confirmed = window.confirm(this.cancelVoucherPromptValue);
+    if (!confirmed) return;
+
+    await post(`${Spree.adminPath}/boxnow/${this.orderIdValue}/cancel`);
+
+    Turbo.visit(window.location.href, { action: "replace" });
+  }
+}

data/app/lib/spree_boxnow/api_client.rb

@@ -0,0 +1,108 @@
+require 'faraday'
+require 'faraday/retry'
+
+module SpreeBoxnow
+  class ApiClient
+    include Spree::IntegrationsConcern
+
+    TOKEN_MARGIN = 60 # seconds before expiry to refresh
+
+    def initialize
+      integration = store_integration('boxnow')
+      raise 'BoxNow integration not configured' unless integration
+
+      @client_id     = integration.preferred_client_id
+      @client_secret = integration.preferred_client_secret
+      @api_url       = integration.preferred_api_url.to_s.chomp('/')
+    end
+
+    def create_delivery_request(params)
+      post('/api/v1/delivery-requests', params)
+    end
+
+    def fetch_label(parcel_id, format: 'pdf')
+      get("/api/v1/parcels/#{parcel_id}/label.#{format}", raw: true)
+    end
+
+    def cancel_parcel(parcel_id)
+      post("/api/v1/parcels/#{parcel_id}:cancel", {})
+    end
+
+    def destinations(params = {})
+      get('/api/v1/destinations', params: params)
+    end
+
+    private
+
+    def token_cache_key
+      "spree_boxnow/access_token/#{@client_id}"
+    end
+
+    def access_token
+      cached = Rails.cache.read(token_cache_key)
+      return cached if cached
+
+      response = Faraday.post(
+        "#{@api_url}/api/v1/auth-sessions",
+        { grant_type: 'client_credentials', client_id: @client_id, client_secret: @client_secret }.to_json,
+        'Content-Type' => 'application/json',
+        'Accept'       => 'application/json'
+      )
+
+      raise ApiError, "Authentication failed (#{response.status}): #{response.body}" unless response.success?
+
+      body       = JSON.parse(response.body)
+      token      = body['access_token']
+      expires_in = body['expires_in'].to_i - TOKEN_MARGIN
+
+      Rails.cache.write(token_cache_key, token, expires_in: expires_in)
+      token
+    end
+
+    def json_connection
+      @json_connection ||= Faraday.new(url: @api_url) do |f|
+        f.request  :json
+        f.response :json
+        f.request  :retry, max: 2, interval: 0.5
+        f.adapter  Faraday.default_adapter
+      end
+    end
+
+    def raw_connection
+      @raw_connection ||= Faraday.new(url: @api_url) do |f|
+        f.request  :retry, max: 2, interval: 0.5
+        f.adapter  Faraday.default_adapter
+      end
+    end
+
+    def get(path, params: {}, raw: false)
+      conn = raw ? raw_connection : json_connection
+      response = conn.get(path) do |req|
+        req.headers['Authorization'] = "Bearer #{access_token}"
+        req.headers['Accept']        = raw ? 'application/pdf' : 'application/json'
+        req.params.merge!(params) unless params.empty?
+      end
+      handle_response(response, raw: raw)
+    end
+
+    def post(path, body)
+      response = json_connection.post(path) do |req|
+        req.headers['Authorization'] = "Bearer #{access_token}"
+        req.body = body
+      end
+      handle_response(response)
+    end
+
+    def handle_response(response, raw: false)
+      unless response.success?
+        code = response.body.is_a?(Hash) ? response.body['code'] : nil
+        message = code ? I18n.t("spree.boxnow.api_errors.#{code}", default: response.body.to_s) : response.body.to_s
+        raise ApiError, "[#{code || response.status}] #{message}"
+      end
+
+      raw ? response.body : response.body
+    end
+
+    class ApiError < StandardError; end
+  end
+end

data/app/models/spree/calculator/shipping/boxnow_rate.rb

@@ -0,0 +1,123 @@
+module Spree
+  module Calculator::Shipping
+    class BoxnowRate < Spree::ShippingCalculator
+      # Hard limits (BoxNow)
+      MAX_WEIGHT_KG  = 20.0
+      MAX_HEIGHT_CM  = 36.0
+      MAX_WIDTH_CM   = 45.0
+      MAX_DEPTH_CM   = 60.0
+
+      # Size thresholds (height decides the size; width/depth are constant limits)
+      SIZE_MAX_HEIGHT_CM = {
+        small:  8.0,
+        medium: 17.0,
+        large:  36.0
+      }.freeze
+
+      preference :small_box_price,  :decimal, default: 0.0
+      preference :medium_box_price, :decimal, default: 0.0
+      preference :large_box_price,  :decimal, default: 0.0
+
+      preference :base_padding_cm,    :decimal, default: 1.0
+      preference :multi_item_factor,  :decimal, default: 1.05
+
+      validates :preferred_small_box_price,
+                :preferred_medium_box_price,
+                :preferred_large_box_price,
+                :preferred_base_padding_cm,
+                :preferred_multi_item_factor,
+                presence: true
+
+      def self.description
+        Spree.t(:shipping_boxnow_rate)
+      end
+
+      def compute_package(package)
+        return nil if package.weight.to_f > MAX_WEIGHT_KG
+
+        dims = estimated_parcel_dimensions_cm(package)
+        return nil if dims.nil?
+
+        dims = apply_packing_margin(dims, package)
+
+        # allow rotation by sorting dims (smallest->height threshold)
+        s, m, d = [dims[:height], dims[:width], dims[:depth]].map(&:to_f).sort
+        return nil if s > MAX_HEIGHT_CM || m > MAX_WIDTH_CM || d > MAX_DEPTH_CM
+
+        size = box_size_for_height(s)
+        return nil unless size
+
+        price_for(size)
+      end
+
+      private
+
+      # Conservative 1-parcel estimate:
+      # - For each item: sort dims s<=m<=d
+      # - Stack along smallest side (s) across quantities => parcel height
+      # - Width = max(m), Depth = max(d) across all items
+      def estimated_parcel_dimensions_cm(package)
+        heights = []
+        widths  = []
+        depths  = []
+
+        package.contents.each do |content|
+          variant = content.variant
+          qty = content.quantity
+
+          dims = variant_dimensions_cm(variant)
+          return nil if dims.nil?
+
+          s, m, d = dims.sort
+          heights << (s * qty)
+          widths  << m
+          depths  << d
+        end
+
+        {
+          height: heights.sum,
+          width:  widths.max || 0.0,
+          depth:  depths.max || 0.0
+        }
+      end
+
+      def apply_packing_margin(dims, package)
+        factor = multi_item?(package) ? preferred_multi_item_factor : 1.0
+
+        {
+          height: (dims[:height].to_f * factor) + preferred_base_padding_cm,
+          width:  (dims[:width].to_f  * factor) + preferred_base_padding_cm,
+          depth:  (dims[:depth].to_f  * factor) + preferred_base_padding_cm
+        }
+      end
+
+      def multi_item?(package)
+        package.contents.sum { |c| c.quantity } > 1
+      end
+
+      def variant_dimensions_cm(variant)
+        height = variant.height.to_f
+        width  = variant.width.to_f
+        depth  = variant.depth.to_f
+
+        return nil if [height, width, depth].any? { |v| v <= 0 }
+
+        [height, width, depth]
+      end
+
+      def box_size_for_height(height_cm)
+        return :small  if height_cm <= SIZE_MAX_HEIGHT_CM[:small]
+        return :medium if height_cm <= SIZE_MAX_HEIGHT_CM[:medium]
+        return :large  if height_cm <= SIZE_MAX_HEIGHT_CM[:large]
+      end
+
+      def price_for(size)
+        case size
+        when :small  then preferred_small_box_price
+        when :medium then preferred_medium_box_price
+        when :large  then preferred_large_box_price
+        end
+      end
+    end
+  end
+end