spree_packeta 0.1.0

data/docs/RELEASING.md

@@ -0,0 +1,421 @@
+# Release Guide for spree_packeta
+
+This guide explains how to create a new release of the spree_packeta gem.
+
+## Prerequisites
+
+1. **Maintainer access**: You must have push access to the repository
+2. **RubyGems account**: Configured as owner of the spree_packeta gem
+3. **GitHub secrets**: `RUBYGEMS_API_KEY` must be configured (maintainers only)
+
+## Dual Publishing
+
+This gem is published to **two registries**:
+- **RubyGems.org**: Public gem registry (primary)
+- **GitHub Packages**: GitHub's gem registry (backup/alternative)
+
+Benefits:
+- **Redundancy**: If RubyGems.org is down, users can install from GitHub Packages
+- **Private gems**: Can be extended for private versions
+- **GitHub integration**: Better integration with GitHub ecosystem
+- **No extra setup required**: `GITHUB_TOKEN` is automatically provided by GitHub Actions
+
+## Release Process
+
+### 1. Prepare the Release
+
+#### Update Version Number
+
+Edit `lib/spree_packeta/version.rb`:
+
+```ruby
+module SpreePacketa
+  VERSION = '1.0.0'  # Change to your new version
+end
+```
+
+Follow [Semantic Versioning](https://semver.org/):
+- **MAJOR** (1.0.0): Breaking changes
+- **MINOR** (0.2.0): New features, backward compatible
+- **PATCH** (0.1.1): Bug fixes, backward compatible
+
+#### Update CHANGELOG.md
+
+Move items from `[Unreleased]` to a new version section:
+
+```markdown
+## [Unreleased]
+
+### Added
+- (empty after release)
+
+## [1.0.0] - 2024-12-21
+
+### Added
+- New feature X
+- New feature Y
+
+### Fixed
+- Bug fix Z
+
+[Unreleased]: https://github.com/yourusername/spree_packeta/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/yourusername/spree_packeta/compare/v0.1.0...v1.0.0
+```
+
+#### Update Documentation
+
+If needed, update:
+- `README.md` - Installation version numbers
+- Code examples with new features
+- Roadmap section
+
+### 2. Pre-Release Checks
+
+Run these commands locally:
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linter (if configured)
+bundle exec rubocop
+
+# Build gem locally to verify
+gem build spree_packeta.gemspec
+# Should output: Successfully built RubyGem
+# Should create: spree_packeta-1.0.0.gem
+
+# Clean up test gem
+rm spree_packeta-*.gem
+```
+
+All checks must pass before proceeding.
+
+### 3. Commit and Tag
+
+```bash
+# Stage changes
+git add lib/spree_packeta/version.rb CHANGELOG.md README.md
+
+# Commit with descriptive message
+git commit -m "Prepare v1.0.0 release
+
+- Update version to 1.0.0
+- Update CHANGELOG with new features and fixes
+- Update README documentation
+"
+
+# Push to main
+git push origin main
+
+# Create annotated tag
+git tag -a v1.0.0 -m "Release v1.0.0"
+
+# Push tag (this triggers the release workflow)
+git push origin v1.0.0
+```
+
+### 4. Monitor Release Workflow
+
+1. Go to GitHub Actions: https://github.com/yourusername/spree_packeta/actions
+2. Find the "Release Gem to RubyGems and GitHub Packages" workflow
+3. Watch the progress through three stages:
+   - ✅ Validate Release (version check)
+   - ✅ Run Tests (RSpec)
+   - ✅ Build and Publish (RubyGems.org + GitHub Packages + GitHub Release)
+
+Expected duration: 3-5 minutes
+
+### 5. Verify Release
+
+After workflow completes:
+
+#### Check RubyGems.org
+```bash
+# Search for new version
+gem search spree_packeta
+
+# Install and verify
+gem install spree_packeta -v 1.0.0
+```
+
+Or visit: https://rubygems.org/gems/spree_packeta
+
+#### Check GitHub Packages
+
+Visit: https://github.com/yourusername/spree_packeta/packages
+
+Should see:
+- Package: spree_packeta
+- Latest version: 1.0.0
+- Published timestamp
+
+Or verify via command line (requires GitHub authentication):
+```bash
+# Configure bundler to use GitHub Packages
+bundle config set --local https://rubygems.pkg.github.com/yourusername <YOUR_GITHUB_TOKEN>
+
+# Then install
+gem install spree_packeta --source https://rubygems.pkg.github.com/yourusername
+```
+
+#### Check GitHub Release
+
+Visit: https://github.com/yourusername/spree_packeta/releases
+
+Should see:
+- Release title: "Release v1.0.0"
+- Auto-generated release notes with installation instructions for both registries
+- Attached gem file: `spree_packeta-1.0.0.gem`
+
+#### Test Installation
+
+In a test Rails app:
+
+```ruby
+# Gemfile
+gem 'spree_packeta', '~> 1.0.0'
+```
+
+```bash
+bundle install
+bundle exec rails g spree_packeta:install
+```
+
+### 6. Announce Release (Optional)
+
+Consider announcing:
+- Twitter/X post
+- Company blog post
+- Spree Community forums
+- Email to users/clients
+
+## Troubleshooting
+
+### Version Mismatch Error
+
+```
+❌ ERROR: Version mismatch!
+Git tag: v1.0.0
+version.rb: 0.9.0
+```
+
+**Solution**:
+```bash
+# Delete the tag
+git tag -d v1.0.0
+git push --delete origin v1.0.0
+
+# Update version.rb to 1.0.0
+# Commit and re-tag
+```
+
+### Test Failures
+
+```
+❌ Run Tests failed
+```
+
+**Solution**:
+```bash
+# Run tests locally to debug
+bundle exec rspec --format documentation
+
+# Fix failing tests
+# Commit fixes
+# Delete and recreate tag
+```
+
+### RubyGems Publish Failed
+
+```
+❌ ERROR: There was a problem saving your gem: Name already exists
+```
+
+**Cause**: Version already published
+
+**Solution**:
+```bash
+# Increment patch version
+# Update version.rb to 1.0.1
+# Commit and create new tag v1.0.1
+```
+
+### GitHub Release Failed
+
+The workflow continues even if GitHub Release creation fails.
+
+**Solution**: Create release manually:
+```bash
+gh release create v1.0.0 \
+  --title "Release v1.0.0" \
+  --notes "See CHANGELOG.md for details" \
+  spree_packeta-1.0.0.gem
+```
+
+### Missing RubyGems API Key
+
+```
+❌ ERROR: Please sign up for an account at http://rubygems.org
+```
+
+**Cause**: `RUBYGEMS_API_KEY` secret not configured or invalid
+
+**Solution**:
+1. Login to rubygems.org
+2. Go to Edit Profile > API Keys
+3. Create new API key with "Push rubygems" scope
+4. Copy the token (shown once)
+5. Add to GitHub: Settings > Secrets and variables > Actions > New repository secret
+   - Name: `RUBYGEMS_API_KEY`
+   - Value: [paste token]
+
+## Rollback Procedures
+
+### Yank a Published Gem
+
+If you need to remove a published version:
+
+```bash
+# Mark version as yanked (users can't install, but existing installs work)
+gem yank spree_packeta -v 1.0.0
+
+# To undo yank
+gem yank spree_packeta -v 1.0.0 --undo
+```
+
+**Note**: Yanking should be rare and only for critical security issues.
+
+### Delete a GitHub Release
+
+```bash
+# Delete release (keeps tag)
+gh release delete v1.0.0 --yes
+
+# Delete tag
+git push --delete origin v1.0.0
+git tag -d v1.0.0
+```
+
+## Setting up RubyGems API Key
+
+For first-time setup or rotation:
+
+### 1. Generate API Key on RubyGems
+
+1. Login to https://rubygems.org
+2. Click on your profile > Edit Profile
+3. Navigate to "API Keys" section
+4. Click "New API Key"
+5. Configure the key:
+   - **Name**: "GitHub Actions - spree_packeta"
+   - **Scopes**: Check "Push rubygems" only
+   - **Gem**: Select "spree_packeta" (or leave blank for all)
+   - **Expiration**: Set appropriate expiration (or leave blank)
+6. Click "Create"
+7. **COPY THE KEY NOW** - it's shown only once
+
+### 2. Add to GitHub Secrets
+
+1. Go to repository on GitHub
+2. Settings > Secrets and variables > Actions
+3. Click "New repository secret"
+4. Name: `RUBYGEMS_API_KEY`
+5. Value: Paste the API key from step 1
+6. Click "Add secret"
+
+### 3. Verify Setup
+
+Test with a patch release:
+
+```bash
+# Update version to 0.1.1
+# Update CHANGELOG
+# Commit and tag
+git tag v0.1.1
+git push origin v0.1.1
+
+# Watch workflow to ensure it completes successfully
+```
+
+## Security Notes
+
+- Never commit API keys or credentials
+- Rotate `RUBYGEMS_API_KEY` periodically (every 6-12 months)
+- Use 2FA on RubyGems account
+- Review dependency updates before releases
+- Run `bundle audit` to check for vulnerabilities
+- Limit API key scope to push-only permissions
+- Set expiration dates on API keys
+
+## Installing from GitHub Packages (for users)
+
+If users want to install your gem from GitHub Packages instead of RubyGems.org:
+
+### Option 1: Using Gemfile source block
+
+```ruby
+# Gemfile
+source 'https://rubygems.pkg.github.com/yourusername' do
+  gem 'spree_packeta', '~> 1.0.0'
+end
+```
+
+Then authenticate:
+```bash
+bundle config set --local https://rubygems.pkg.github.com/yourusername <GITHUB_TOKEN>
+bundle install
+```
+
+### Option 2: Using gem command
+
+```bash
+# Configure credentials
+gem sources --add https://rubygems.pkg.github.com/yourusername
+
+# Install
+gem install spree_packeta --source https://rubygems.pkg.github.com/yourusername
+```
+
+**Note**: GitHub Packages requires authentication. Users need a GitHub Personal Access Token with `read:packages` scope.
+
+## FAQ
+
+**Q: Can I release from a branch other than main?**
+A: The workflow triggers on any tag push, regardless of branch. However, it's recommended to always release from main after merging all changes.
+
+**Q: What if I need to release a hotfix?**
+A: Create a hotfix branch, make changes, update version to a patch increment (e.g., 1.0.1), merge to main, then tag and push.
+
+**Q: How do I handle pre-releases (beta, rc)?**
+A: Currently, the workflow only supports stable releases (v1.0.0). For pre-releases, you'd need to manually publish or extend the tag regex pattern.
+
+**Q: What happens if the workflow fails midway?**
+A: The workflow is designed to fail-fast:
+- If validation fails: Nothing is published
+- If tests fail: Nothing is published
+- If RubyGems.org publish fails: GitHub Packages is not published
+- If GitHub Packages publish fails: Workflow continues (RubyGems.org is primary)
+- If GitHub Release fails: Gems are already published (manual release creation needed)
+
+**Q: What if GitHub Packages publishing fails?**
+A: GitHub Packages publishing is considered non-critical. If it fails, the workflow continues and the gem is still available on RubyGems.org. You can manually publish to GitHub Packages later if needed.
+
+**Q: How do I test the workflow without publishing?**
+A: You can test validation and build steps by:
+1. Running `gem build` locally
+2. Checking the workflow logs on a test tag
+3. Using a separate test gem name for initial setup
+
+**Q: Can I skip the tests?**
+A: Not recommended. Tests are a quality gate. If you absolutely must, you can modify the workflow to remove the test job dependency.
+
+**Q: Do users need special setup to use my gem from GitHub Packages?**
+A: Yes, they need a GitHub Personal Access Token with `read:packages` scope. For most users, installing from RubyGems.org is simpler and recommended.
+
+## Questions?
+
+Contact the maintainers or open an issue on GitHub.

data/lib/generators/spree_packeta/install_generator.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module SpreePacketa
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Installs Spree Packeta and generates necessary files'
+
+      def copy_initializer
+        template 'initializer.rb', 'config/initializers/spree_packeta.rb'
+        say 'Initializer created at config/initializers/spree_packeta.rb', :green
+      end
+
+      def copy_migrations
+        rake 'railties:install:migrations FROM=spree_packeta'
+        say 'Migrations copied', :green
+      end
+
+      def run_migrations
+        if options[:auto_run_migrations] || yes?('Run migrations now? (yes/no)')
+          rake 'db:migrate'
+          say 'Migrations completed', :green
+        else
+          say 'Skipping migrations. Run `rails db:migrate` manually', :yellow
+        end
+      end
+
+      def install_shipping_method
+        if options[:skip_shipping_method]
+          say 'Skipping shipping method installation', :yellow
+        elsif yes?('Install Packeta shipping method now? (yes/no)')
+          rake 'spree_packeta:install'
+        else
+          say 'You can install the shipping method later with: rake spree_packeta:install', :yellow
+        end
+      end
+
+      def show_readme
+        say ''
+        say '=' * 80, :green
+        say 'Spree Packeta Installation Complete!', :green
+        say '=' * 80, :green
+        say ''
+        say 'Next steps:', :yellow
+        say ''
+        say '  1. Add your Packeta credentials to .env:', :cyan
+        say '     PACKETA_API_PASSWORD=your_api_password'
+        say '     PACKETA_ESHOP=your_eshop_id'
+        say '     PACKETA_WSDL_PATH=file:///path/to/soap.wsdl'
+        say '     PACKETA_SENDER_EMAIL=shipping@yourstore.com'
+        say ''
+        say '  2. Restart your Rails server', :cyan
+        say ''
+        say '  3. Configure shipping method in Spree admin', :cyan
+        say '     or run: rake spree_packeta:install (if you skipped it)'
+        say ''
+        say '  4. Frontend integration:', :cyan
+        say '     See FRONTEND_INTEGRATION.md for React/frontend setup'
+        say ''
+        say 'Documentation:', :yellow
+        say '  - README.md - General usage'
+        say '  - FRONTEND_INTEGRATION.md - Frontend setup guide'
+        say ''
+      end
+    end
+  end
+end

data/lib/generators/spree_packeta/templates/initializer.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+SpreePacketa.configure do |config|
+  # API credentials
+  # Get your API password from Packeta dashboard
+  config.api_password = ENV['PACKETA_API_PASSWORD']
+
+  # SOAP endpoint (production vs sandbox)
+  # Default: http://www.zasilkovna.cz/api/soap
+  # Sandbox: http://www.zasilkovna.cz/api/soap-php-bugfix (if available)
+  config.soap_endpoint = ENV.fetch('PACKETA_SOAP_ENDPOINT',
+                                    'http://www.zasilkovna.cz/api/soap')
+
+  # WSDL path (can be local file or remote URL)
+  # Use local file for better performance: file:///path/to/soap.wsdl
+  # Or use remote: http://www.zasilkovna.cz/api/soap.wsdl
+  config.wsdl_path = ENV.fetch('PACKETA_WSDL_PATH',
+                                'http://www.zasilkovna.cz/api/soap.wsdl')
+
+  # Your Eshop identifier from Packeta
+  config.eshop = ENV['PACKETA_ESHOP']
+
+  # Sender information (for return labels and contact)
+  config.sender_name = ENV.fetch('PACKETA_SENDER_NAME', 'Your Store Name')
+  config.sender_email = ENV.fetch('PACKETA_SENDER_EMAIL', 'shipping@yourstore.com')
+  config.sender_phone = ENV.fetch('PACKETA_SENDER_PHONE', '+420123456789')
+
+  # Rate caching duration (in seconds)
+  # How long to cache shipping rate calculations
+  config.rate_cache_duration = 3600 # 1 hour
+
+  # Auto-create packets on shipment
+  # Set to true to automatically create Packeta packets when order is shipped
+  config.auto_create_packets = true
+
+  # Tracking sync interval (in seconds)
+  # How often to sync tracking status from Packeta
+  config.tracking_sync_interval = 3600 # 1 hour
+end

data/lib/spree_packeta/configuration.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module SpreePacketa
+  class Configuration
+    # API credentials
+    attr_accessor :api_password
+
+    # SOAP endpoint (production vs sandbox)
+    attr_accessor :soap_endpoint
+
+    # Default eshop identifier
+    attr_accessor :eshop
+
+    # Sender information for return labels
+    attr_accessor :sender_name
+    attr_accessor :sender_email
+    attr_accessor :sender_phone
+
+    # Rate caching duration (in seconds)
+    attr_accessor :rate_cache_duration
+
+    # Auto-create packets on shipment
+    attr_accessor :auto_create_packets
+
+    # Sync tracking status interval
+    attr_accessor :tracking_sync_interval
+
+    # WSDL file path (can be local or remote)
+    attr_accessor :wsdl_path
+
+    def initialize
+      @soap_endpoint = 'http://www.zasilkovna.cz/api/soap'
+      @rate_cache_duration = 3600 # 1 hour
+      @auto_create_packets = true
+      @tracking_sync_interval = 3600 # 1 hour in seconds
+      @wsdl_path = 'http://www.zasilkovna.cz/api/soap.wsdl'
+    end
+  end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/spree_packeta/engine.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'spree_core'
+
+module SpreePacketa
+  class Engine < Rails::Engine
+    require 'spree/core'
+    isolate_namespace Spree
+    engine_name 'spree_packeta'
+
+    config.autoload_paths += %W[#{config.root}/lib]
+
+    # use rspec for tests
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    def self.activate
+      # Load decorators
+      Dir.glob(File.join(File.dirname(__FILE__), '../../app/**/*_decorator*.rb')) do |c|
+        Rails.configuration.cache_classes ? require(c) : load(c)
+      end
+
+      # Load gem components after Spree has been initialized
+      require 'spree_packeta/soap/client'
+      require 'spree_packeta/soap/operations'
+      require 'spree_packeta/models/shipping_method'
+      require 'spree_packeta/models/shipping_calculator'
+      require 'spree_packeta/services/packet_creator'
+      require 'spree_packeta/services/tracker'
+    end
+
+    config.to_prepare(&method(:activate).to_proc)
+
+    initializer 'spree_packeta.environment', before: :load_config_initializers do |_app|
+      SpreePacketa.configure do |config|
+        # Load configuration from environment variables
+        config.api_password = ENV['PACKETA_API_PASSWORD'] if ENV['PACKETA_API_PASSWORD']
+        config.soap_endpoint = ENV['PACKETA_SOAP_ENDPOINT'] if ENV['PACKETA_SOAP_ENDPOINT']
+        config.eshop = ENV['PACKETA_ESHOP'] if ENV['PACKETA_ESHOP']
+        config.sender_name = ENV['PACKETA_SENDER_NAME'] if ENV['PACKETA_SENDER_NAME']
+        config.sender_email = ENV['PACKETA_SENDER_EMAIL'] if ENV['PACKETA_SENDER_EMAIL']
+        config.sender_phone = ENV['PACKETA_SENDER_PHONE'] if ENV['PACKETA_SENDER_PHONE']
+        config.wsdl_path = ENV['PACKETA_WSDL_PATH'] if ENV['PACKETA_WSDL_PATH']
+      end
+    end
+  end
+end

data/lib/spree_packeta/models/shipping_calculator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module SpreePacketa
+  module Models
+    class ShippingCalculator < Spree::ShippingCalculator
+      # Preference for base shipping rate
+      preference :amount, :decimal, default: 99.0
+      preference :currency, :string, default: 'CZK'
+
+      # Calculate shipping rate for a package
+      #
+      # @param package [Spree::Stock::Package] The package to calculate for
+      # @return [BigDecimal] The shipping cost
+      def compute_package(package)
+        return 0 if package.contents.empty?
+
+        # For Phase 1, use fixed rate from preferences
+        # Phase 2 will implement dynamic rate calculation via Packeta API
+        base_rate = BigDecimal(preferred_amount.to_s)
+
+        # Apply weight-based multiplier if needed
+        total_weight = calculate_total_weight(package)
+        weight_multiplier = calculate_weight_multiplier(total_weight)
+
+        (base_rate * weight_multiplier).round(2)
+      end
+
+      private
+
+      def calculate_total_weight(package)
+        package.contents.sum do |item|
+          weight = item.variant.weight.to_f
+          quantity = item.quantity
+          weight * quantity
+        end
+      end
+
+      def calculate_weight_multiplier(weight)
+        # Simple weight-based pricing tiers
+        # Adjust these based on your business needs
+        case weight
+        when 0..5
+          1.0
+        when 5..10
+          1.2
+        when 10..20
+          1.5
+        else
+          2.0
+        end
+      end
+    end
+  end
+end