an_post_return 0.2.0

data/README.md

@@ -0,0 +1,166 @@
+# AnPostReturn
+
+A Ruby gem for integrating with An Post's return label generation and tracking service. This gem provides a simple interface for creating return labels for domestic, EU, and non-EU returns, and tracking through An Post's SFTP service.
+
+## Features
+
+- Generate return labels for domestic, EU, and non-EU returns
+- SFTP integration for secure file transfer
+- Simple configuration options
+- Proxy option for An Post IP whitelisting purpose
+- Robust error handling
+- Comprehensive tracking data parsing
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'an_post_return'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install an_post_return
+```
+
+## Configuration
+
+Configure the gem with your An Post credentials:
+
+```ruby
+AnPostReturn.configure do |config|
+  # API Configuration (required)
+  config.subscription_key = 'your_subscription_key'  # The Ocp-Apim-Subscription-Key for authentication
+
+  # SFTP Configuration (required)
+  config.sftp_config = {
+    host: 'your_sftp_host',
+    username: 'your_username',
+    password: 'your_password',
+    remote_path: '/path/to/remote/files'  # The remote directory where An Post places tracking files
+  }
+
+  # Optional proxy configuration (for An Post IP whitelisting)
+  config.proxy_config = {
+    host: 'proxy-host',
+    port: 'proxy-port',
+    user: 'proxy-user',     # Optional proxy authentication
+    password: 'proxy-password'  # Optional proxy authentication
+  }
+
+  # Environment setting
+  config.test = false # Set to true for sandbox environment
+end
+```
+
+## Usage
+
+### Creating a Return Label
+
+```ruby
+# Initialize a new return label request
+client = AnPostReturn::Client.new
+response = client.return_labels.create(
+  output_response_type: "Label",
+  sender: {
+    first_name: "Jane",
+    last_name: "Smith",
+    contact_number: "0871234567",
+    email_address: "test@email.com"
+  },
+  sender_address: {
+    address_line1: "Exo Building",
+    address_line2: "North Wall Quay",
+    city: "Dublin 1",
+    eircode: "D01 W5Y2",
+    county: "Dublin",
+    country: "Ireland",
+    countrycode: "IE"
+  },
+  retailer_account_no: "your_account_number",
+  retailer_return_reason: "Does not fit",
+  retailer_order_number: "987654321"
+)
+
+# Access the response data
+puts response["trackingNumber"]  # The An Post tracking number for this shipment
+puts response["labelData"]       # The label data (usually a PDF bitstream)
+```
+
+### Tracking Shipments
+
+The tracking system works with An Post's SFTP service, where tracking files are named in the format:
+`CDT99999999SSSSS.txt` where:
+
+- CDT is the prefix (Customer Data Tracking)
+- 99999999 is your An Post Customer Account Number
+- SSSSS is a sequence number (starts at 1, increments by 1 for each file)
+- .txt is the file extension
+
+```ruby
+tracker = AnPostReturn::Tracker.new
+
+# Track by account number (gets all files)
+# This will retrieve all tracking files for the given account number
+tracker.track_with_account_number("3795540") do |file, data|
+  puts "Processing file: #{file}"
+  puts "Tracking data: #{data}"
+end
+
+# Track by account number (get last N files)
+# Useful when you only want recent tracking updates
+tracker.track_with_account_number("3795540", last: 2) do |file, data|
+  puts "Processing file: #{file}"
+  puts "Tracking data: #{data}"
+end
+
+# Track from a specific file onwards, by incrementing file name by 1 until no file is found
+# Useful for resuming tracking from a known point
+tracker.track_from("cdt0370132115864.txt") do |file, data|
+  puts "Processing file: #{file}"
+  puts "Tracking data: #{data}"
+end
+```
+
+The tracking data structure contains:
+
+- `:header` - File header information including account details
+- `:data` - Array of tracking events for multiple shipments
+- `:footer` - File footer information including totals
+
+Possible tracking statuses:
+
+- "SORTED" - Item has been sorted at An Post facility
+- "ATTEMPTED DELIVERY" - Delivery was attempted but not completed
+- "DELIVERED" - Item has been successfully delivered
+- "ITEM ON HAND" - Item is being held at An Post facility
+- "PRE-ADVICE" - Item is expected but not yet received
+- "OUT FOR DELIVERY" - Item is on the delivery vehicle
+- "ITEM ACCEPTED" - Item has been received by An Post
+- "CUSTOMER INSTRUCTION REC" - Customer has provided special instructions
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/PostCo/an_post_return. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/PostCo/an_post_return/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the AnPostReturn project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/PostCo/an_post_return/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/lib/an_post_return/client.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require_relative "configuration"
+require_relative "errors"
+
+module AnPostReturn
+  class Client
+    attr_reader :config
+
+    def initialize
+      @config = AnPostReturn.configuration
+    end
+
+    def return_labels
+      @return_labels ||= Resources::ReturnLabelResource.new(self)
+    end
+
+    def connection
+      @connection ||=
+        Faraday.new(url: config.api_base_url) do |faraday|
+          faraday.proxy = config.proxy_uri if config.proxy_configured?
+
+          faraday.request :json
+          faraday.response :json
+          faraday.adapter Faraday.default_adapter
+          faraday.headers = default_headers
+        end
+    end
+
+    private
+
+    def default_headers
+      {
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        "Ocp-Apim-Subscription-Key" => config.subscription_key,
+      }
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        if response.body.is_a?(Hash) && response.body["success"] == false
+          raise APIError.new(
+                  "API request failed with status #{response.status}: #{parse_error_message(response)}",
+                  response: response,
+                )
+        else
+          response.body
+        end
+      when 400
+        raise ValidationError.new(parse_error_message(response), response: response)
+      when 401
+        raise ConfigurationError.new("Invalid subscription key", response: response)
+      when 404
+        raise APIError.new("Resource not found", response: response)
+      when 407
+        raise ConfigurationError.new("Proxy authentication required", response: response)
+      else
+        raise APIError.new(
+                "API request failed with status #{response.status}: #{parse_error_message(response)}",
+                response: response,
+              )
+      end
+    end
+
+    def parse_error_message(response)
+      if response.body.is_a?(Hash) && response.body["errors"]
+        errors = response.body["errors"]
+        if errors.is_a?(Array)
+          return errors.map { |error| error["message"] }.join(", ")
+        else
+          return errors
+        end
+      end
+
+      "Unknown error"
+    end
+  end
+end

data/lib/an_post_return/configuration.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module AnPostReturn
+  class Configuration
+    attr_accessor :test
+    attr_accessor :proxy_config
+    attr_accessor :sftp_config
+    attr_accessor :subscription_key
+
+    def initialize
+      @test = false
+      @proxy_config = nil
+      @sftp_config = nil
+      @subscription_key = nil
+    end
+
+    def api_base_url
+      if test
+        "https://apim-anpost-mailslabels-nonprod.dev-anpost.com/returnsapi-q/v2"
+      else
+        "https://apim-anpost-mailslabels.anpost.com/returnsapi/v2"
+      end
+    end
+
+    def proxy_configured?
+      !proxy_config.nil?
+    end
+
+    def proxy_uri
+      return nil unless proxy_configured?
+
+      uri = "http://#{proxy_config[:host]}:#{proxy_config[:port]}"
+      uri =
+        "http://#{proxy_config[:user]}:#{proxy_config[:password]}@#{proxy_config[:host]}:#{proxy_config[:port]}" if proxy_config[
+        :user
+      ] && proxy_config[:password]
+      URI.parse(uri)
+    end
+
+    def sftp_configured?
+      return false if sftp_config.nil?
+
+      required_keys = %i[host username password remote_path]
+      required_keys.all? { |key| sftp_config.key?(key) && !sftp_config[key].nil? }
+    end
+  end
+end

data/lib/an_post_return/errors.rb

@@ -0,0 +1,21 @@
+module AnPostReturn
+  class ParserError < StandardError
+  end
+  class Error < StandardError
+    attr_reader :response
+
+    def initialize(message, response: nil)
+      @response = response
+      super(message)
+    end
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class APIError < Error
+  end
+
+  class ValidationError < Error
+  end
+end

data/lib/an_post_return/objects/base.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/string"
+require "active_support/hash_with_indifferent_access"
+require "ostruct"
+
+module AnPostReturn
+  class Base < OpenStruct
+    attr_reader :original_response
+
+    def initialize(attributes)
+      @original_response = attributes
+      super to_ostruct(attributes)
+    end
+
+    def to_ostruct(obj)
+      if obj.is_a?(Hash)
+        OpenStruct.new(obj.map { |key, val| [key.to_s.underscore, to_ostruct(val)] }.to_h)
+      elsif obj.is_a?(Array)
+        obj.map { |o| to_ostruct(o) }
+      else # Assumed to be a primitive value
+        obj
+      end
+    end
+
+    # Return the original response with camelCase keys preserved
+    def response
+      @original_response
+    end
+
+    # Convert back to hash without table key, including nested structures
+    def to_hash
+      ostruct_to_hash(self)
+    end
+
+    # Override comparison to handle hash comparison
+    def ==(other)
+      case other
+      when Hash
+        to_hash == other
+      else
+        super
+      end
+    end
+
+    # Override eql? to be consistent with ==
+    def eql?(other)
+      self == other
+    end
+
+    private
+
+    def ostruct_to_hash(object)
+      case object
+      when OpenStruct
+        hash = object.to_h.reject { |k, _| k == :table }
+        # Convert to HashWithIndifferentAccess and process values recursively
+        ActiveSupport::HashWithIndifferentAccess.new(hash).transform_values { |value| ostruct_to_hash(value) }
+      when Array
+        object.map { |item| ostruct_to_hash(item) }
+      when Hash
+        # Convert to HashWithIndifferentAccess and process values recursively
+        ActiveSupport::HashWithIndifferentAccess.new(object).transform_values { |value| ostruct_to_hash(value) }
+      else
+        object
+      end
+    end
+  end
+end

data/lib/an_post_return/objects/return_label.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module AnPostReturn
+  class ReturnLabel < Base
+    def success?
+      success
+    end
+  end
+end

data/lib/an_post_return/resources/return_label_resource.rb

@@ -0,0 +1,123 @@
+require_relative "../objects/return_label"
+module AnPostReturn
+  module Resources
+    class ReturnLabelResource
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      # Create a return label
+      # @param params [Hash] The parameters for creating a return label
+      # @option params [String] :output_response_type Type of response ('Label')
+      # @option params [Hash] :sender Sender information
+      #   @option sender [String] :first_name Sender's first name
+      #   @option sender [String] :last_name Sender's last name
+      #   @option sender [String] :contact_number Sender's contact number
+      #   @option sender [String] :email_address Sender's email address
+      # @option params [Hash] :sender_address Sender's address details
+      #   @option sender_address [String] :address_line1 First line of address
+      #   @option sender_address [String] :address_line2 Second line of address (optional)
+      #   @option sender_address [String] :city City
+      #   @option sender_address [String] :eircode Eircode
+      #   @option sender_address [String] :county County
+      #   @option sender_address [String] :country Country name
+      #   @option sender_address [String] :countrycode Country code (ISO 3166-1 alpha-2)
+      # @option params [String] :retailer_account_no Your An Post account number
+      # @option params [String] :retailer_return_reason Reason for return
+      # @option params [String] :retailer_order_number Order number
+      # @option params [Array<Hash>] :international_security_declaration_items Required for EU returns
+      #   @option international_security_declaration_items [String] :item_description Description of item
+      # @option params [Hash] :customs_information Required for non-EU returns
+      #   @option customs_information [String] :customs_region_code Customs region code
+      #   @option customs_information [Integer] :customs_category_id Category ID
+      #   @option customs_information [Float] :weight Weight in kg
+      #   @option customs_information [Float] :value_amount Value amount
+      #   @option customs_information [Float] :postage_fee_paid Postage fee paid
+      #   @option customs_information [Float] :insured_value Insured value
+      #   @option customs_information [Array<Hash>] :customs_content_items Content items for customs
+      #     @option customs_content_items [Integer] :list_order Order in list
+      #     @option customs_content_items [Integer] :number_of_units Number of units
+      #     @option customs_content_items [String] :description Item description
+      #     @option customs_content_items [String] :hs_tarriff HS tariff code
+      #     @option customs_content_items [Float] :value_amount Item value
+      #     @option customs_content_items [Float] :weight Item weight
+      #     @option customs_content_items [String] :country_of_origin Country of origin code
+      # @return [AReturnLabel] The created return label data
+      #
+      # @example Create a domestic return label
+      #   client.return_labels.create({
+      #     output_response_type: "Label",
+      #     sender: {
+      #       first_name: "Jane",
+      #       last_name: "Smith",
+      #       contact_number: "0871234567",
+      #       email_address: "test@email.com"
+      #     },
+      #     sender_address: {
+      #       address_line1: "Exo Building",
+      #       address_line2: "North Wall Quay",
+      #       city: "Dublin 1",
+      #       eircode: "D01 W5Y2",
+      #       county: "Dublin",
+      #       country: "Ireland",
+      #       countrycode: "IE"
+      #     },
+      #     retailer_account_no: "your_account_number",
+      #     retailer_return_reason: "Does not fit",
+      #     retailer_order_number: "987654321"
+      #   })
+      #
+      # @example Create an EU return label
+      #   client.return_labels.create({
+      #     output_response_type: "Label",
+      #     sender: { ... },
+      #     sender_address: { ... },
+      #     international_security_declaration_items: [
+      #       { item_description: "book" }
+      #     ],
+      #     retailer_account_no: "your_account_number",
+      #     retailer_return_reason: "Does not fit",
+      #     retailer_order_number: "123456789"
+      #   })
+      #
+      # @example Create a non-EU return label
+      #   client.return_labels.create({
+      #     customs_information: {
+      #       customs_region_code: "1",
+      #       customs_category_id: 2,
+      #       weight: 1.5,
+      #       value_amount: 55,
+      #       postage_fee_paid: 1,
+      #       insured_value: 55,
+      #       customs_content_items: [
+      #         {
+      #           list_order: 1,
+      #           number_of_units: 1,
+      #           description: "shoes",
+      #           hs_tarriff: "6404191000",
+      #           value_amount: 55,
+      #           weight: 1.5,
+      #           country_of_origin: "IE"
+      #         }
+      #       ]
+      #     },
+      #     output_response_type: "Label",
+      #     sender: { ... },
+      #     sender_address: { ... },
+      #     retailer_account_no: "your_account_number",
+      #     retailer_return_reason: "Does not fit",
+      #     retailer_order_number: "321654987"
+      #   })
+      def create(params)
+        raise ArgumentError, "Missing required parameters" if params.nil?
+        raise ArgumentError, "Subscription key not configured" if client.config.subscription_key.nil?
+
+        response = client.connection.post("returnsLabel") { |req| req.body = params }
+        response_data = client.send(:handle_response, response)
+        ReturnLabel.new(response_data)
+      end
+    end
+  end
+end

data/lib/an_post_return/sftp/client.rb

@@ -0,0 +1,132 @@
+require "net/sftp"
+require "net/ssh/proxy/http"
+require "tempfile"
+require "csv"
+require "x25519"
+require_relative "errors"
+
+module AnPostReturn
+  module SFTP
+    class Client
+      # SFTP connection configuration
+      attr_reader :host, :username, :password, :proxy_config
+
+      # Initialize a new SFTP client
+      #
+      # @param host [String] SFTP server hostname
+      # @param username [String] SFTP username
+      # @param password [String] SFTP password
+      # @param proxy_config [Hash, nil] Optional HTTP proxy configuration
+      #   @option proxy_config [String] :host Proxy host
+      #   @option proxy_config [Integer] :port Proxy port
+      #   @option proxy_config [String, nil] :username Optional proxy username
+      #   @option proxy_config [String, nil] :password Optional proxy password
+      def initialize(host, username, password, proxy_config = nil)
+        @host = host
+        @username = username
+        @password = password
+        @proxy_config = proxy_config
+        @connected = false
+      end
+
+      # Establish SFTP connection
+      #
+      # @return [Boolean] true if connection successful, false otherwise
+      # @raise [AnPostReturn::SFTP::ConnectionError] if connection fails
+      def connect
+        sftp_client.connect!
+        @connected = true
+        true
+      rescue Net::SSH::Exception => e
+        raise ConnectionError, "Failed to connect to #{host}: #{e.message}"
+      end
+
+      # Close SFTP connection
+      #
+      # @return [void]
+      def disconnect
+        return unless @connected
+
+        sftp_client.close_channel
+        ssh_session.close
+        @connected = false
+      end
+
+      # Download and read a file from SFTP server
+      #
+      # @param remote_path [String] Path to file on SFTP server
+      # @yield [Tempfile] Temporary file containing downloaded content
+      # @return [Tempfile, Object] If block given, returns block result; otherwise returns Tempfile
+      # @raise [AnPostReturn::SFTP::FileError] if file download fails
+      def read_file(remote_path)
+        ensure_connected
+        temp_file = Tempfile.new(["sftp", File.extname(remote_path)])
+
+        begin
+          sftp_client.download!(remote_path, temp_file.path)
+          block_given? ? yield(temp_file) : temp_file
+        rescue Net::SFTP::StatusException => e
+          if e.message.include?("no such file")
+            raise FileNotFoundError
+          else
+            raise FileError, "Failed to download #{remote_path}: #{e.message}"
+          end
+        ensure
+          unless block_given?
+            temp_file.close
+            temp_file.unlink
+          end
+        end
+      end
+
+      # List files in remote directory
+      #
+      # @param remote_path [String] Remote directory path
+      # @param glob_pattern [String, nil] Optional glob pattern for filtering files
+      # @return [Array<Net::SFTP::Protocol::V01::Name>] Array of file entries
+      # @raise [AnPostReturn::SFTP::FileError] if listing files fails
+      def list_files(remote_path, glob_pattern = nil)
+        ensure_connected
+        entries = []
+
+        begin
+          if glob_pattern
+            sftp_client.dir.glob(remote_path, glob_pattern) { |entry| entries << entry }
+          else
+            sftp_client.dir.foreach(remote_path) { |entry| entries << entry }
+          end
+          entries
+        rescue Net::SFTP::StatusException => e
+          raise FileError, "Failed to list files in #{remote_path}: #{e.message}"
+        end
+      end
+
+      private
+
+      def sftp_client
+        @sftp_client ||= Net::SFTP::Session.new(ssh_session)
+      end
+
+      def ssh_session
+        return @ssh_session if @ssh_session
+
+        ssh_options = { password: password, auth_methods: ["password"] }
+
+        if proxy_config
+          ssh_options[:proxy] = Net::SSH::Proxy::HTTP.new(
+            proxy_config[:host],
+            proxy_config[:port],
+            user: proxy_config[:username],
+            password: proxy_config[:password],
+          )
+        end
+
+        @ssh_session = Net::SSH.start(host, username, ssh_options)
+      end
+
+      def ensure_connected
+        raise ConnectionError, "Not connected to SFTP server" unless @connected
+      end
+    end
+  end
+end

data/lib/an_post_return/sftp/errors.rb

@@ -0,0 +1,12 @@
+module AnPostReturn
+  module SFTP
+    class Error < StandardError
+    end
+    class ConnectionError < Error
+    end
+    class FileError < Error
+    end
+    class FileNotFoundError < FileError
+    end
+  end
+end