spree_packeta 0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+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,307 @@
+# Spree Packeta
+
+Packeta (Zasilkovna) shipping integration for Spree Commerce. This gem provides SOAP API integration for packet creation, tracking, and label generation.
+
+## Features
+
+- **Phase 1 (Current)**:
+  - SOAP client wrapper for Packeta API
+  - Packet creation and tracking
+  - Shipping method and calculator integration
+  - Database tracking fields for shipments
+
+- **Planned Features**:
+  - Dynamic rate calculation from Packeta API
+  - Label generation (PDF, PNG, ZPL)
+  - COD (Cash on Delivery) support
+  - Customs declarations
+  - Admin interface for packet management
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'spree_packeta', path: '/Users/oezr/Projects/spree_packeta'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Run the installation generator:
+
+```bash
+bundle exec rails g spree_packeta:install
+```
+
+This will:
+- Copy the migration files
+- Create an initializer with configuration
+- Optionally run migrations
+- Optionally install the Packeta shipping method
+
+### Manual Installation
+
+If you prefer to install components separately:
+
+```bash
+# Copy and run migrations
+bundle exec rails spree_packeta:install:migrations
+bundle exec rails db:migrate
+
+# Install Packeta shipping method
+bundle exec rake spree_packeta:install
+
+# Check status
+bundle exec rake spree_packeta:status
+```
+
+## Configuration
+
+Configure the gem in `config/initializers/spree_packeta.rb`:
+
+```ruby
+SpreePacketa.configure do |config|
+  # API credentials
+  config.api_password = ENV['PACKETA_API_PASSWORD']
+
+  # SOAP endpoint (production vs sandbox)
+  config.soap_endpoint = ENV.fetch('PACKETA_SOAP_ENDPOINT',
+                                    'http://www.zasilkovna.cz/api/soap')
+
+  # WSDL path (can be local file or URL)
+  config.wsdl_path = ENV.fetch('PACKETA_WSDL_PATH',
+                                'http://www.zasilkovna.cz/api/soap.wsdl')
+
+  # Default eshop identifier
+  config.eshop = ENV['PACKETA_ESHOP']
+
+  # Sender information for return labels
+  config.sender_name = ENV['PACKETA_SENDER_NAME']
+  config.sender_email = ENV['PACKETA_SENDER_EMAIL']
+  config.sender_phone = ENV['PACKETA_SENDER_PHONE']
+
+  # Rate caching duration (in seconds)
+  config.rate_cache_duration = 3600 # 1 hour
+
+  # Auto-create packets on shipment
+  config.auto_create_packets = true
+
+  # Sync tracking status interval
+  config.tracking_sync_interval = 1.hour
+end
+```
+
+### Environment Variables
+
+Add these to your `.env` file:
+
+```env
+PACKETA_API_PASSWORD=your_api_password_here
+PACKETA_ESHOP=your_eshop_identifier
+PACKETA_SENDER_NAME=Your Store Name
+PACKETA_SENDER_EMAIL=shipping@yourstore.com
+PACKETA_SENDER_PHONE=+420123456789
+
+# Optional: Use local WSDL file
+PACKETA_WSDL_PATH=file:///path/to/soap.wsdl
+```
+
+## Usage
+
+### Quick Start with Rake Tasks
+
+The easiest way to set up Packeta:
+
+```bash
+# Install shipping method with default configuration
+bundle exec rake spree_packeta:install
+
+# Check installation status and configuration
+bundle exec rake spree_packeta:status
+
+# Remove shipping method if needed
+bundle exec rake spree_packeta:uninstall
+```
+
+The `install` task will:
+- Create "Packeta" shipping method
+- Set up Czech Republic and EU zones
+- Configure the Packeta calculator with default rates (99 CZK)
+- Assign shipping categories and zones
+
+### Manual Setup via Admin Panel
+
+If you prefer manual setup or need to customize:
+
+1. Go to Settings → Shipping Methods
+2. Click "New Shipping Method"
+3. Fill in:
+   - **Name**: Packeta
+   - **Admin Name**: Packeta (Zásilkovna)
+   - **Code**: packeta
+   - **Display**: Both (or your preference)
+   - **Tracking URL**: `https://tracking.packeta.com/:tracking`
+   - **Shipping Categories**: Select applicable categories
+   - **Calculator**: Choose "Packeta Shipping Calculator"
+4. Configure calculator preferences:
+   - **Amount**: Base shipping rate (e.g., 99.00)
+   - **Currency**: CZK (or your currency)
+5. Assign to zones (Czech Republic, EU, etc.)
+
+### Creating a Packet
+
+The gem provides services for packet management:
+
+```ruby
+# Create a packet from a shipment
+service = SpreePacketa::Services::PacketCreator.new(shipment)
+result = service.create_packet
+
+# This will:
+# - Extract shipment details
+# - Call Packeta API to create packet
+# - Store packet ID and barcode on shipment
+# - Return packet details
+```
+
+### Tracking
+
+```ruby
+# Get current status
+tracker = SpreePacketa::Services::Tracker.new(shipment)
+status = tracker.current_status
+# => { date_time: ..., status_code: ..., status_text: ..., branch_id: ... }
+
+# Get full tracking history
+history = tracker.tracking_history
+# => [{ date_time: ..., status_code: ..., ... }, ...]
+```
+
+### Direct SOAP API Access
+
+For advanced use cases, you can use the SOAP operations directly:
+
+```ruby
+# Initialize operations
+ops = SpreePacketa::Soap::Operations.new
+
+# Create a packet
+packet = ops.create_packet(
+  number: 'ORDER-12345',
+  name: 'John',
+  surname: 'Doe',
+  email: 'john@example.com',
+  phone: '+420123456789',
+  address_id: 1234, # Packeta pickup point ID
+  value: 1000.0,
+  weight: 2.5,
+  currency: 'CZK'
+)
+# => { id: 123456, barcode: '...', barcode_text: 'Z...' }
+
+# Get packet status
+status = ops.packet_status(packet[:id])
+# => { status_code: 1, status_text: 'Packet created', ... }
+
+# Get tracking history
+history = ops.packet_tracking(packet[:id])
+# => [{ date_time: ..., status_code: ..., ... }, ...]
+```
+
+## Database Schema
+
+The gem adds the following columns to `spree_shipments`:
+
+| Column                    | Type     | Description                          |
+|---------------------------|----------|--------------------------------------|
+| `packeta_packet_id`       | bigint   | Packeta packet ID                    |
+| `packeta_barcode`         | string   | Packet barcode                       |
+| `packeta_tracking_url`    | string   | Full tracking URL                    |
+| `packeta_status_code`     | integer  | Latest status code                   |
+| `packeta_branch_id`       | integer  | Current branch/pickup point ID       |
+| `packeta_last_sync_at`    | datetime | Last tracking sync timestamp         |
+
+## Error Handling
+
+The gem defines custom exceptions for different error scenarios:
+
+```ruby
+begin
+  ops.create_packet(attributes)
+rescue SpreePacketa::AuthenticationError => e
+  # Invalid API password
+rescue SpreePacketa::ValidationError => e
+  # Invalid packet attributes
+rescue SpreePacketa::NotFoundError => e
+  # Packet not found
+rescue SpreePacketa::NetworkError => e
+  # Network/connectivity issues
+rescue SpreePacketa::ApiError => e
+  # Other API errors
+end
+```
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+### Running Tests
+
+```bash
+bundle exec rspec
+```
+
+### Console
+
+```bash
+bundle exec bin/console
+```
+
+## Roadmap
+
+### Phase 2: Rate Calculation
+- [ ] Dynamic rate calculation via Packeta API
+- [ ] Zone-based pricing
+- [ ] Service level support
+- [ ] Rate caching
+
+### Phase 3: Label Generation
+- [ ] PDF label generation
+- [ ] Multiple format support (PNG, ZPL)
+- [ ] Batch label generation
+- [ ] Label storage
+
+### Phase 4: Advanced Features
+- [ ] COD support
+- [ ] Customs declarations
+- [ ] Pickup point widget
+- [ ] Return shipments
+- [ ] Packet updates
+
+### Phase 5: Admin Interface
+- [ ] Packeta settings page
+- [ ] Packet management
+- [ ] Bulk operations
+- [ ] Tracking dashboard
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/spree_packeta.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Support
+
+For issues specific to this gem, please open an issue on GitHub.
+
+For Packeta API documentation and support, visit: https://www.zasilkovna.cz/api/

data/app/decorators/spree/order_decorator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module SpreePacketa
+  module OrderDecorator
+    def self.prepended(base)
+      base.class_eval do
+        set_callback :updating_from_params, :before, :update_packeta_pickup_point
+
+        # Store Packeta pickup point data in order metadata
+        store_accessor :public_metadata, :packeta_pickup_point_id
+        store_accessor :public_metadata, :packeta_pickup_point_name
+        store_accessor :public_metadata, :packeta_pickup_point_address
+      end
+    end
+
+    def update_packeta_pickup_point
+      return unless @updating_params[:order] && @updating_params[:order][:packeta_pickup_point].present?
+      set_packeta_pickup_point(@updating_params[:order].delete(:packeta_pickup_point))
+    end
+
+    # Get the Packeta pickup point ID for this order
+    #
+    # @return [Integer, nil] The pickup point ID
+    def packeta_address_id
+      packeta_pickup_point_id&.to_i
+    end
+
+    # Set Packeta pickup point from widget data
+    #
+    # @param point_data [Hash] Pickup point data from Packeta widget
+    def set_packeta_pickup_point(point_data)
+      return unless point_data
+
+      self.packeta_pickup_point_id = point_data[:id]
+      self.packeta_pickup_point_name = point_data[:name]
+
+      address_parts = [point_data[:street], point_data[:city], point_data[:zip]].compact
+
+      self.packeta_pickup_point_address = address_parts.join(', ')
+    end
+
+    Spree::Order.prepend self
+  end
+end

data/app/decorators/spree/shipment_decorator.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SpreePacketa
+  module ShipmentDecorator
+    def self.prepended(base)
+      base.class_eval do
+        # Hook into state machine - after successful transition to 'ready'
+        state_machine.after_transition to: :ready, do: :auto_create_packeta_packet
+      end
+    end
+
+    private
+
+    # Automatically create Packeta packet when shipment becomes ready
+    # This method is called after state transition to 'ready' is committed
+    # Errors are caught and logged but never block the shipment workflow
+    def auto_create_packeta_packet
+      # Early returns for conditions that prevent auto-creation
+      return unless should_auto_create_packet?
+
+      # Delegate to service for actual creation
+      packet_creator = SpreePacketa::Services::PacketCreator.new(self)
+      result = packet_creator.create_packet
+
+      Rails.logger.info("Auto-created Packeta packet #{result[:id]} for shipment #{id}")
+    rescue SpreePacketa::ValidationError => e
+      Rails.logger.warn("Automatic Packeta packet creation skipped for shipment #{id}: #{e.message}")
+    rescue SpreePacketa::NetworkError, SpreePacketa::ApiError => e
+      Rails.logger.error("Packeta API error during auto-creation for shipment #{id}: #{e.message}")
+    rescue StandardError => e
+      Rails.logger.error("Unexpected error during Packeta auto-creation for shipment #{id}: #{e.class} - #{e.message}")
+      Rails.logger.error(e.backtrace.first(10).join("\n"))
+    end
+
+    # Determine if automatic packet creation should proceed
+    def should_auto_create_packet?
+      # Check global configuration
+      return false unless SpreePacketa.configuration.auto_create_packets
+
+      # Check if packet already exists
+      return false if packeta_packet_id.present?
+
+      # Check if this is a Packeta shipment
+      return false unless packeta_shipping_method?
+
+      # Check if pickup point is selected
+      return false unless order.packeta_pickup_point_id.present?
+
+      true
+    end
+
+    # Check if the shipping method is a Packeta shipping method
+    def packeta_shipping_method?
+      return false unless shipping_method
+
+      # Check if it's our Packeta shipping method class
+      return true if shipping_method.is_a?(SpreePacketa::Models::ShippingMethod)
+
+      # Fallback: check carrier name for admin-configured methods
+      shipping_method.carrier == 'Packeta'
+    end
+
+    Spree::Shipment.prepend self
+  end
+end

data/db/migrate/20241206000001_add_packeta_tracking_to_shipments.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class AddPacketaTrackingToShipments < ActiveRecord::Migration[7.0]
+  def change
+    add_column :spree_shipments, :packeta_packet_id, :bigint
+    add_column :spree_shipments, :packeta_barcode, :string
+    add_column :spree_shipments, :packeta_tracking_url, :string
+    add_column :spree_shipments, :packeta_status_code, :integer
+    add_column :spree_shipments, :packeta_branch_id, :integer
+    add_column :spree_shipments, :packeta_last_sync_at, :datetime
+
+    add_index :spree_shipments, :packeta_packet_id, unique: true, name: 'index_shipments_on_packeta_packet_id'
+  end
+end