spree_boxnow 1.0.0 → 1.2.0

checksums.yaml

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

data/README.md

@@ -34,16 +34,16 @@ A [Spree Commerce](https://spreecommerce.org) extension that integrates **BoxNow
 
 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 |
+| 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.
 
@@ -56,12 +56,12 @@ The shipping calculator determines the price tier from the physical dimensions o
 
 BoxNow hard limits:
 
-| Dimension | Limit |
-|-----------|-------|
+| Dimension  | Limit |
+| ---------- | ----- |
 | Max weight | 20 kg |
 | Max height | 36 cm |
-| Max width | 45 cm |
-| Max depth | 60 cm |
+| Max width  | 45 cm |
+| Max depth  | 60 cm |
 
 ### 3. Create a BoxNow shipping method
 
@@ -72,13 +72,13 @@ Go to **Admin → Shipping Methods → New**:
 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. |
+| 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. |
 
 ---
 
@@ -87,17 +87,18 @@ Go to **Admin → Shipping Methods → New**:
 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 |
+| 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.
 
@@ -159,12 +160,12 @@ If a voucher creation attempt fails and the admin retries, the extension appends
 
 ## 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 |
+| 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) |
 
 ---

data/app/lib/spree_boxnow/phone_normalizer.rb

@@ -0,0 +1,19 @@
+require 'phonelib'
+
+module SpreeBoxnow
+  # Normalizes phone numbers to the full international (E.164) format BoxNow
+  # requires, e.g. +306912345678. `country_iso` is the ISO 3166-1 alpha-2
+  # code used to interpret a number given in national format (defaults to
+  # GR, since BoxNow only operates in Greece); numbers already given in
+  # international format (leading +) are parsed as-is regardless.
+  module PhoneNormalizer
+    module_function
+
+    def call(phone, country_iso = nil)
+      return '' if phone.blank?
+
+      parsed = Phonelib.parse(phone, country_iso || 'GR')
+      parsed.valid? ? parsed.e164 : phone.to_s
+    end
+  end
+end

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

@@ -7,7 +7,7 @@ module Spree
       MAX_WIDTH_CM   = 45.0
       MAX_DEPTH_CM   = 60.0
 
-      # Size thresholds (height decides the size; width/depth are constant limits)
+      # Size thresholds — tier is determined by the smallest sorted dimension
       SIZE_MAX_HEIGHT_CM = {
         small:  8.0,
         medium: 17.0,
@@ -18,8 +18,8 @@ module Spree
       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
+      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,
@@ -32,53 +32,163 @@ module Spree
         Spree.t(:shipping_boxnow_rate)
       end
 
+      SIZES_ORDERED = %i[small medium large].freeze
+
       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?
+        boxes = minimum_bounding_boxes(package)
+        return nil if boxes.nil?
 
-        dims = apply_packing_margin(dims, package)
+        best_size = nil
 
-        # 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
+        boxes.each do |sml|
+          padded = apply_packing_margin({ height: sml[0], width: sml[1], depth: sml[2] }, package)
+          s, m, d = [padded[:height], padded[:width], padded[:depth]].map(&:to_f).sort
+          next if s > MAX_HEIGHT_CM || m > MAX_WIDTH_CM || d > MAX_DEPTH_CM
 
-        size = box_size_for_height(s)
-        return nil unless size
+          size = box_size_for_height(s)
+          next unless size
+
+          best_size = smaller_size(best_size, size)
+        end
 
-        price_for(size)
+        return nil unless best_size
+
+        price_for(best_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
+      # Exhaustive recursive bounding-box search over all item orientations and
+      # all possible groupings (hierarchical binary splits).
+      #
+      # Each line item (distinct SKU) is treated as a block in one of up to 3
+      # orientations — one per choice of which dimension is multiplied by qty.
+      # The solver tries every binary partition of line items into two groups,
+      # combines the Pareto-optimal bounding boxes of each group along 3 axes,
+      # and Pareto-prunes the result. Memoisation by sorted index set ensures
+      # each subset is computed exactly once.
+      #
+      # N = distinct line items (SKUs), not total quantity.
+      # 100 identical keycards = 1 line item = N=1 → trivially fast.
+      # For very large N (many distinct SKUs), a time-based execution guard
+      # can be added if observed to be slow in production.
+      def minimum_bounding_boxes(package)
+        all_items = package.contents.map do |content|
+          orientations = item_block_orientations(content.variant, content.quantity)
+          return nil if orientations.nil?
+          orientations
         end
 
-        {
-          height: heights.sum,
-          width:  widths.max || 0.0,
-          depth:  depths.max || 0.0
-        }
+        return all_items[0] if all_items.size == 1
+
+        solve_boxes((0...all_items.size).to_a, all_items, {})
+      end
+
+      # Recursive memoised solver.
+      # indices   — sorted Array<Integer> identifying this subset within all_items
+      # all_items — Array<Array<[s,m,l]>>, per-item orientation sets
+      # cache     — Hash keyed by sorted index array
+      def solve_boxes(indices, all_items, cache)
+        return cache[indices] if cache.key?(indices)
+
+        result =
+          if indices.size == 1
+            all_items[indices[0]]
+          else
+            # Pin indices[0] in the left group and vary what else joins it.
+            # This enumerates every unordered binary partition exactly once.
+            rest     = indices[1..]
+            combined = []
+
+            0.upto(rest.size - 1) do |left_size|
+              rest.combination(left_size).each do |left_extra|
+                left_indices  = ([indices[0]] + left_extra).sort
+                right_indices = (rest - left_extra).sort
+                next if right_indices.empty?
+
+                boxes_a = solve_boxes(left_indices,  all_items, cache)
+                boxes_b = solve_boxes(right_indices, all_items, cache)
+
+                boxes_a.each do |a|
+                  boxes_b.each do |b|
+                    combined.concat(combine_sorted_boxes(a, b))
+                  end
+                end
+              end
+            end
+
+            pareto_optimal(combined)
+          end
+
+        cache[indices] = result
+      end
+
+      # Combines two sorted triples [s1,m1,l1] and [s2,m2,l2] along each of
+      # the 3 axes (sum one dimension, max the other two), re-sorts each result
+      # to model free physical rotation, and returns the Pareto-optimal subset.
+      def combine_sorted_boxes(box_a, box_b)
+        s1, m1, l1 = box_a
+        s2, m2, l2 = box_b
+
+        pareto_optimal([
+          [s1 + s2,        [m1, m2].max, [l1, l2].max].sort,
+          [[s1, s2].max,   m1 + m2,      [l1, l2].max].sort,
+          [[s1, s2].max,   [m1, m2].max, l1 + l2      ].sort
+        ])
+      end
+
+      # Removes dominated boxes from a collection of sorted triples.
+      # Box X dominates box Y if X[i] <= Y[i] for all i with at least one strict.
+      def pareto_optimal(boxes)
+        boxes.reject do |candidate|
+          boxes.any? do |other|
+            next false if other.equal?(candidate)
+            other[0] <= candidate[0] &&
+              other[1] <= candidate[1] &&
+              other[2] <= candidate[2] &&
+              other != candidate
+          end
+        end.uniq
+      end
+
+      # Returns all distinct sorted [s,m,l] orientations for a line item.
+      # For each factorization of qty into (a,b,c) with a*b*c == qty, and for
+      # each permutation of (a,b,c) assigned to the item's 3 dimensions, the
+      # bounding box is computed and sorted (free rotation). This covers linear
+      # stacking, 2-D grids, and 3-D grids (e.g. 2x5 arrangement of 10 items).
+      def item_block_orientations(variant, qty)
+        dims = variant_dimensions_cm(variant)
+        return nil if dims.nil?
+
+        h, w, d = dims
+        orientations = []
+
+        qty_factorizations(qty).each do |a, b, c|
+          [a, b, c].permutation.each do |fa, fb, fc|
+            orientations << [h * fa, w * fb, d * fc].sort
+          end
+        end
+
+        orientations.uniq
+      end
+
+      # Returns all sorted triples [a, b, c] with a <= b <= c and a*b*c == n.
+      def qty_factorizations(n)
+        result = []
+        a = 1
+        while a * a * a <= n
+          if n % a == 0
+            b = a
+            while a * b * b <= n
+              result << [a, b, n / (a * b)] if (n / a) % b == 0
+              b += 1
+            end
+          end
+          a += 1
+        end
+        result
       end
 
       def apply_packing_margin(dims, package)
@@ -105,6 +215,11 @@ module Spree
         [height, width, depth]
       end
 
+      def smaller_size(a, b)
+        return b if a.nil?
+        SIZES_ORDERED.index(a) <= SIZES_ORDERED.index(b) ? a : b
+      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]

data/app/services/spree_boxnow/create_voucher.rb

@@ -31,13 +31,13 @@ module SpreeBoxnow
         origin: {
           locationId:    integration.preferred_origin_location_id,
           contactName:   integration.preferred_contact_name.presence || '',
-          contactNumber: integration.preferred_contact_phone.presence || '',
+          contactNumber: PhoneNormalizer.call(integration.preferred_contact_phone),
           contactEmail:  integration.preferred_contact_email.presence || ''
         },
         destination: {
           locationId:    destination_id,
           contactName:   address.full_name,
-          contactNumber: address.phone.to_s,
+          contactNumber: PhoneNormalizer.call(address.phone, address.country_iso),
           contactEmail:  order.email.to_s
         },
         items: [{

data/lib/spree_boxnow/version.rb

@@ -1,5 +1,5 @@
 module SpreeBoxnow
-  VERSION = '1.0.0'.freeze
+  VERSION = '1.2.0'.freeze
 
   def gem_version
     Gem::Version.new(VERSION)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spree_boxnow
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - OlympusOne
@@ -107,6 +107,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: phonelib
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
 - !ruby/object:Gem::Dependency
   name: spree_dev_tools
   requirement: !ruby/object:Gem::Requirement
@@ -136,6 +150,7 @@ files:
 - app/javascript/spree_boxnow/application.js
 - app/javascript/spree_boxnow/controllers/spree_boxnow_controller.js
 - app/lib/spree_boxnow/api_client.rb
+- app/lib/spree_boxnow/phone_normalizer.rb
 - app/models/spree/calculator/shipping/boxnow_rate.rb
 - app/models/spree/integrations/boxnow.rb
 - app/models/spree/order_decorator.rb
@@ -167,10 +182,10 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/olympusone/spree_boxnow/issues
-  changelog_uri: https://github.com/olympusone/spree_boxnow/releases/tag/v1.0.0
+  changelog_uri: https://github.com/olympusone/spree_boxnow/releases/tag/v1.2.0
   documentation_uri: https://github.com/olympusone/spree_boxnow
   homepage_uri: https://github.com/olympusone/spree_boxnow
-  source_code_uri: https://github.com/olympusone/spree_boxnow/tree/v1.0.0
+  source_code_uri: https://github.com/olympusone/spree_boxnow/tree/v1.2.0
 rdoc_options: []
 require_paths:
 - lib