dpd_ie_api 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b91d20b8a6d5d06abf9897fab59bf99ac71490104e2a5dfb730cc32db671fd6
-  data.tar.gz: ef2e9119ec01c8fcda0e82fb99d03ccd5c340d6ec69a0746a8b659599e7d8848
+  metadata.gz: cb11635fe7a354bb8985d5edb82b4e61ae916ed43010849df6add2ef62d6c439
+  data.tar.gz: f29f052b67496fd4558640cc53bbaf381ff8e6e8baaaa94cb1bb57079d6d3e96
 SHA512:
-  metadata.gz: 6d3683adbfe882a5938337ffaa442c174ddf5089138aeae2107d205acd2aeccd7fd0bd9e9dd3d92757066864faf54a841a2de9728decad57792d9da80a03358f
-  data.tar.gz: 4edec2a71897a299239641de7b4246d7fd3a1baf3e9fbc2a67bf0a6c3f6e1f7c5a431c01cf538a1139cd8eb040bcfef35c76b599914d8eb4a98aa48b990c7ca6
+  metadata.gz: 11361928734bebad3eeb835f74cc7c2c3801010617f417fdb9c7187966ef12d8f25f0072c633ae2edea68580516ae160bc35b128604fba54ede9867819c735b0
+  data.tar.gz: 6c2fb2b988f85e0e0cda8fa5f5aa54209c5ad675b863361ccf647538c68571f1e17f6ead4493e8bf870122800dc1d58985293e10fcd4ec98ce6b9ed4e75725ff

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/README.md

@@ -1,34 +1,183 @@
 # DpdIeApi
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/dpd_ie_api`. To experiment with that code, run `bin/console` for an interactive prompt.
+A Ruby gem wrapper for the DPD Ireland API.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```bash
+bundle add dpd_ie_api
+```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```bash
+gem install dpd_ie_api
+```
+
+## Design
+
+The gem provides a **uniform Ruby interface** across all endpoints. You always work with Ruby hashes and objects — the gem picks the best format (JSON or XML) for each endpoint internally:
+
+| Endpoint | Request Format | Response Format |
+|----------|---------------|-----------------|
+| Authorize | JSON | JSON |
+| PreAdvice | XML | XML |
+| Track | XML | JSON |
+
+JSON is used wherever the DPD API supports it (simpler, no XML parsing overhead). XML is used only where the API requires it. This is entirely invisible to gem consumers.
 
 ## Usage
 
-TODO: Write usage instructions here
+### Authentication
+
+Obtain an access token using your static token and credentials.
+
+```ruby
+auth = DpdIeApi::Auth.fetch_token("YOUR_STATIC_TOKEN", "YOUR_USER", "YOUR_PASSWORD")
+access_token = auth.access_token
+refresh_token = auth.refresh_token
+expires_in = auth.expires_in
+```
+
+> [!IMPORTANT]
+> The access token expires after a certain period (indicated by `expires_in`). It is highly recommended to cache the `access_token` and reuse it until it expires to avoid unnecessary API calls and potential rate limiting.
+
+For production, pass `prod: true`:
+
+```ruby
+auth = DpdIeApi::Auth.fetch_token("YOUR_STATIC_TOKEN", "YOUR_USER", "YOUR_PASSWORD", prod: true)
+```
+
+Then, initialize the client with your access token:
+
+```ruby
+client = DpdIeApi::Client.new(
+  access_token,
+  prod: true  # set to true for production, false for pre-production (default)
+)
+```
+
+**Client constructor:**
+
+- `access_token` - Bearer token from `DpdIeApi::Auth.fetch_token` (required)
+- `prod:` - Set to `true` for production (`https://papi.dpd.ie`), `false` for pre-production (`https://pre-prod-papi.dpd.ie`). Defaults to `false`.
+
+### Error Handling
+
+All endpoints raise `DpdIeApi::Error` on failure. The error object exposes both HTTP status code and response body:
+
+```ruby
+begin
+  client.preadvice.create(payload)
+rescue DpdIeApi::Error => error
+  puts error.message
+  puts error.response_http_code
+  puts error.response_body
+end
+```
+
+### Preadvice
+
+#### Create
+
+Create a preadvice consignment. Pass a Ruby hash — the gem handles XML serialization internally.
+
+```ruby
+payload = {
+  consignment: {
+    record_id: '1',
+    customer_account: '5993L3',
+    total_parcels: '1',
+    relabel: '1',
+    service_option: '5',
+    service_type: '1',
+    weight: '5',
+    delivery_address: {
+      contact: 'Warehouse address',
+      contact_telephone: '0877777777',
+      contact_email: 'test.email@no-email.gg',
+      business_name: 'Shop name',
+      address_line1: 'Trimgate St',
+      address_line2: 'Athlone Business Park',
+      address_line3: 'Navan',
+      address_line4: 'Meath',
+      post_code: 'N37XK83',
+      country_code: 'IE',
+    },
+    collection_address: {
+      contact: 'Customer address',
+      contact_telephone: '0877777777',
+      contact_email: 'test.email@no-email.gg',
+      business_name: 'Customer name',
+      address_line1: '40 Drumcondra Rd Lower',
+      address_line2: '',
+      address_line3: 'Drumcondra',
+      address_line4: 'Dublin',
+      post_code: 'N37XK83',
+      country_code: 'IE'
+    },
+    references: [
+      { reference_name: 'Reference1', reference_value: 'Order Name 123', parcel_number: '1' },
+    ]
+  }
+}
+
+result = client.preadvice.create(payload)
+puts result.status
+puts result.consignment.tracking_number
+puts result.consignment.label_image
+```
+
+> [!NOTE]
+> Hash keys can be symbols (snake_case, auto-converted to PascalCase XML elements) or strings (passed through as-is for exact control). For example, use `"RecordID" => '1'` if the API requires a specific casing that differs from the automatic conversion.
+
+### Track
+
+#### Find
+
+Retrieve tracking information for a consignment.
+
+```ruby
+tracking = client.track.find("800436802")
+
+puts tracking.tracking_number
+puts tracking.consignment_number
+puts tracking.consignment_status
+puts tracking.consignment_service
+
+# Tracking history events
+event = tracking.tracking_history.event_detail
+puts event.event_date
+puts event.event_time
+puts event.event_type_name
+puts event.event_depot_name
+```
+
+The `tracking_type` defaults to `"consignment"` but can be overridden:
+
+```ruby
+tracking = client.track.find("800436802", tracking_type: "parcel")
+```
+
+### Response Objects
+
+All endpoints return response objects that provide:
+
+- **Dot notation access** — `result.consignment.tracking_number` (keys are auto-underscored)
+- **`#raw`** — the original parsed response hash with original PascalCase keys
+- **`#to_hash`** — convert the response object back to a Ruby hash
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` 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/[USERNAME]/dpd_ie_api. 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/[USERNAME]/dpd_ie_api/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/postco/dpd_ie_api. 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/dpd_ie_api/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -36,4 +185,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the DpdIeApi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/dpd_ie_api/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the DpdIeApi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/postco/dpd_ie_api/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -1,4 +1,8 @@
 # frozen_string_literal: true
 
 require 'bundler/gem_tasks'
-task default: %i[]
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/dpd_ie_api/auth.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module DpdIeApi
+  class Auth
+    PROD_BASE_URL = 'https://papi.dpd.ie'
+    TEST_BASE_URL = 'https://pre-prod-papi.dpd.ie'
+    AUTH_PATH = '/common/api/authorize'
+
+    def self.fetch_token(static_token, user, password, prod: false)
+      base_url = prod ? PROD_BASE_URL : TEST_BASE_URL
+      url = "#{base_url}#{AUTH_PATH}"
+
+      response = Faraday.post(url) do |req|
+        req.headers['Authorization'] = "Basic #{static_token}"
+        req.headers['Content-Type'] = 'application/json'
+        req.headers['Accept'] = 'application/json'
+        req.body = { 'User' => user, 'Password' => password, 'Type' => 'CUST' }.to_json
+      end
+
+      unless response.success?
+        raise DpdIeApi::Error.new(
+          "Failed to authorize: #{response.status} - #{response.body}",
+          response_http_code: response.status,
+          response_body: response.body
+        )
+      end
+
+      parsed = JSON.parse(response.body)
+
+      if parsed['Status'] == 'FAIL'
+        raise DpdIeApi::Error.new(
+          "Authorization error: #{parsed['Reason']}",
+          response_http_code: response.status,
+          response_body: response.body
+        )
+      end
+
+      Objects::Auth.new(parsed)
+    end
+  end
+end

data/lib/dpd_ie_api/client.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module DpdIeApi
+  class Client
+    PROD_BASE_URL = 'https://papi.dpd.ie'
+    TEST_BASE_URL = 'https://pre-prod-papi.dpd.ie'
+
+    def initialize(access_token, prod: false)
+      @access_token = access_token
+      @prod = prod
+    end
+
+    def base_url
+      @prod ? PROD_BASE_URL : TEST_BASE_URL
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: base_url) do |f|
+        f.headers['Authorization'] = "Bearer #{@access_token}"
+        f.headers['Content-Type'] = 'application/xml'
+      end
+    end
+
+    def preadvice
+      Resources::Preadvice.new(self)
+    end
+
+    def track
+      Resources::Track.new(self)
+    end
+  end
+end

data/lib/dpd_ie_api/objects/auth.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module DpdIeApi
+  module Objects
+    class Auth < Base
+    end
+  end
+end

data/lib/dpd_ie_api/objects/base.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/string'
+require 'ostruct'
+
+module DpdIeApi
+  module Objects
+    class Base < OpenStruct
+      attr_reader :original_response
+
+      def initialize(attributes)
+        @original_response = deep_freeze_object(attributes)
+        super(to_ostruct(attributes))
+      end
+
+      def to_ostruct(obj)
+        if obj.is_a?(Hash)
+          OpenStruct.new(obj.transform_keys { |key| key.to_s.underscore }.transform_values { |val| to_ostruct(val) })
+        elsif obj.is_a?(Array)
+          obj.map { |o| to_ostruct(o) }
+        else
+          obj
+        end
+      end
+
+      def to_hash
+        ostruct_to_hash(self)
+      end
+
+      def raw
+        @original_response
+      end
+
+      private
+
+      def deep_freeze_object(obj)
+        case obj
+        when Hash
+          obj.transform_values { |value| deep_freeze_object(value) }.freeze
+        when Array
+          obj.map { |item| deep_freeze_object(item) }.freeze
+        else
+          obj.respond_to?(:freeze) ? obj.freeze : obj
+        end
+      end
+
+      def ostruct_to_hash(object)
+        case object
+        when OpenStruct
+          hash = object.to_h.except(:table)
+          hash.transform_keys(&:to_s).transform_values { |value| ostruct_to_hash(value) }
+        when Array
+          object.map { |item| ostruct_to_hash(item) }
+        when Hash
+          object.transform_keys(&:to_s).transform_values { |value| ostruct_to_hash(value) }
+        else
+          object
+        end
+      end
+    end
+  end
+end

data/lib/dpd_ie_api/objects/preadvice.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module DpdIeApi
+  module Objects
+    class Preadvice < Base
+    end
+  end
+end

data/lib/dpd_ie_api/objects/track.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module DpdIeApi
+  module Objects
+    class Track < Base
+    end
+  end
+end

data/lib/dpd_ie_api/resources/preadvice.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module DpdIeApi
+  module Resources
+    class Preadvice
+      PREADVICE_PATH = '/common/api/preadvice'
+
+      def initialize(client)
+        @client = client
+      end
+
+      def create(payload)
+        xml_body = DpdIeApi::XmlBuilder.build('PreAdvice', payload)
+
+        response = @client.connection.post(PREADVICE_PATH) do |req|
+          req.body = xml_body
+        end
+
+        unless response.success?
+          raise DpdIeApi::Error.new(
+            "Failed to create preadvice: #{response.status} - #{response.body}",
+            response_http_code: response.status,
+            response_body: response.body
+          )
+        end
+
+        parsed = DpdIeApi::XmlParser.parse(response.body, '//PreAdviceResponse')
+
+        if parsed['Status'] == 'FAIL'
+          raise DpdIeApi::Error.new(
+            "Preadvice error: #{parsed['PreAdviceErrorDetails']}",
+            response_http_code: response.status,
+            response_body: response.body
+          )
+        end
+
+        Objects::Preadvice.new(parsed)
+      end
+    end
+  end
+end

data/lib/dpd_ie_api/resources/track.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module DpdIeApi
+  module Resources
+    class Track
+      TRACK_PATH = '/common/api/track'
+
+      def initialize(client)
+        @client = client
+      end
+
+      def find(tracking_number, tracking_type: 'consignment')
+        xml_body = build_tracking_xml(tracking_number, tracking_type)
+
+        response = @client.connection.post(TRACK_PATH) do |req|
+          req.headers['Accept'] = 'application/json'
+          req.body = xml_body
+        end
+
+        unless response.success?
+          raise DpdIeApi::Error.new(
+            "Failed to track consignment: #{response.status} - #{response.body}",
+            response_http_code: response.status,
+            response_body: response.body
+          )
+        end
+
+        parsed = JSON.parse(response.body)
+
+        if parsed['TrackingErrorInfo']
+          error_info = unwrap(parsed['TrackingErrorInfo'])
+          error_detail = unwrap(error_info['TrackingErrorDetail'])
+          raise DpdIeApi::Error.new(
+            "Tracking error: #{error_detail['ErrorDetailCodeDesc']}",
+            response_http_code: response.status,
+            response_body: response.body
+          )
+        end
+
+        Objects::Track.new(unwrap(parsed['TrackingInfo']))
+      end
+
+      private
+
+      def unwrap(value)
+        value.is_a?(Array) ? value.first : value
+      end
+
+      def build_tracking_xml(tracking_number, tracking_type)
+        DpdIeApi::XmlBuilder.build('TrackingRequest', {
+                                     request_line: {
+                                       tracking_number: tracking_number,
+                                       tracking_type: tracking_type
+                                     }
+                                   })
+      end
+    end
+  end
+end

data/lib/dpd_ie_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DpdIeApi
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

data/lib/dpd_ie_api/xml_builder.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require 'active_support/core_ext/string/inflections'
+
+module DpdIeApi
+  class XmlBuilder
+    def self.build(root_name, data)
+      builder = Nokogiri::XML::Builder.new(encoding: 'iso-8859-1') do |xml|
+        xml.send(root_name) do
+          hash_to_xml(xml, data)
+        end
+      end
+      builder.to_xml
+    end
+
+    class << self
+      private
+
+      def hash_to_xml(xml, data)
+        data.each do |key, value|
+          element_name = normalize_key(key)
+
+          case value
+          when Hash
+            xml.send(element_name) do
+              hash_to_xml(xml, value)
+            end
+          when Array
+            xml.send(element_name) do
+              child_name = element_name.singularize
+              value.each do |item|
+                if item.is_a?(Hash)
+                  xml.send(child_name) do
+                    hash_to_xml(xml, item)
+                  end
+                else
+                  xml.send(child_name, item.to_s)
+                end
+              end
+            end
+          else
+            xml.send(element_name, value.to_s)
+          end
+        end
+      end
+
+      def normalize_key(key)
+        case key
+        when Symbol then key.to_s.camelize
+        when String then key
+        end
+      end
+    end
+  end
+end

data/lib/dpd_ie_api/xml_parser.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module DpdIeApi
+  class XmlParser
+    def self.parse(body, root_xpath)
+      doc = Nokogiri::XML(body)
+      root = doc.at_xpath(root_xpath)
+      xml_node_to_hash(root)
+    end
+
+    class << self
+      private
+
+      def xml_node_to_hash(node)
+        return nil if node.nil?
+
+        children = node.element_children
+
+        return node.text if children.empty?
+
+        result = {}
+        children.each do |child|
+          key = child.name
+          if result.key?(key)
+            result[key] = [result[key]] unless result[key].is_a?(Array)
+            result[key] << xml_node_to_hash(child)
+          else
+            result[key] = xml_node_to_hash(child)
+          end
+        end
+        result
+      end
+    end
+  end
+end

data/lib/dpd_ie_api.rb

@@ -1,8 +1,25 @@
 # frozen_string_literal: true
 
-require_relative "dpd_ie_api/version"
+require_relative 'dpd_ie_api/version'
+require_relative 'dpd_ie_api/objects/base'
+require_relative 'dpd_ie_api/objects/auth'
+require_relative 'dpd_ie_api/objects/preadvice'
+require_relative 'dpd_ie_api/objects/track'
+require_relative 'dpd_ie_api/xml_builder'
+require_relative 'dpd_ie_api/xml_parser'
+require_relative 'dpd_ie_api/auth'
+require_relative 'dpd_ie_api/client'
+require_relative 'dpd_ie_api/resources/preadvice'
+require_relative 'dpd_ie_api/resources/track'
 
 module DpdIeApi
-  class Error < StandardError; end
-  # Your code goes here...
+  class Error < StandardError
+    attr_reader :response_http_code, :response_body
+
+    def initialize(message = nil, response_http_code: nil, response_body: nil)
+      @response_http_code = response_http_code
+      @response_body = response_body
+      super(message)
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dpd_ie_api
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Linh Ho
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: Provides a Ruby interface for interacting with the DPD Ireland API, including
   authorization, label generation, and tracking.
 email:
@@ -60,22 +88,33 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".rspec"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/dpd_ie_api.rb
+- lib/dpd_ie_api/auth.rb
+- lib/dpd_ie_api/client.rb
+- lib/dpd_ie_api/objects/auth.rb
+- lib/dpd_ie_api/objects/base.rb
+- lib/dpd_ie_api/objects/preadvice.rb
+- lib/dpd_ie_api/objects/track.rb
+- lib/dpd_ie_api/resources/preadvice.rb
+- lib/dpd_ie_api/resources/track.rb
 - lib/dpd_ie_api/version.rb
+- lib/dpd_ie_api/xml_builder.rb
+- lib/dpd_ie_api/xml_parser.rb
 - sig/dpd_ie_api.rbs
-homepage: https://github.com/hplinh0702/dpd_ie_api
+homepage: https://github.com/postco/dpd_ie_api
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/hplinh0702/dpd_ie_api
-  source_code_uri: https://github.com/hplinh0702/dpd_ie_api
-  changelog_uri: https://github.com/hplinh0702/dpd_ie_api/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/postco/dpd_ie_api
+  source_code_uri: https://github.com/postco/dpd_ie_api
+  changelog_uri: https://github.com/postco/dpd_ie_api/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths: