poczta_polska 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7322e491795261baaea74814da021c85e74f6871
+  data.tar.gz: e43dfa728803d4ec87f47bcf087cbd1b98ba5e2c
+SHA512:
+  metadata.gz: 512d79b3af228bde0e7e207836308b4189744fd4a21d6e3c40234d2c2bfcd46a5b9772fe523d7409adc272c390cc88a708903db70293159b1171524b010fabf7
+  data.tar.gz: 59c8fac3a62de475997076ef96de874a7af71599d0a44af48bfae57a6988f19dc7c2e8a93ef3558f5ecfd2f25758b08f5f834748874b7e24870323a340a6a380

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.2.1

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in poczta_polska.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Mikołaj Rozwadowski
+
+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,64 @@
+# PocztaPolska
+
+With this gem you can monitor Polish Post parcels and registered mail
+as well as packages shipped by Pocztex. It allows you to see basic data
+about the consignment as well as all the post offices it has gone through
+(including their locations and opening hours). The data is downloaded from
+[a public SOAP API of the Polish Post](http://www.poczta-polska.pl/pliki/webservices/Metody%20i%20struktury%20uslugi%20sieciowej%20Poczty%20Polskiej%20SA.pdf)
+and wrapped into Ruby classes for your convenience.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'poczta_polska'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install poczta_polska
+
+## Usage
+
+```ruby
+require 'poczta_polska'
+
+package_id = 'testp0'
+# this package ID generates test data
+
+tr = PocztaPolska::tracker
+
+begin
+  pkg = tr.check(package_id)
+
+  puts "A package was sent from #{pkg.office_from} to #{pkg.office_to}."
+
+  pkg.events.each do |event|
+    datetime = event.time.strftime("%F, %R")
+    puts "Finally:" if event.final?
+    puts "Time: #{datetime}"
+    puts "Event: #{event.name}"
+    puts "Post office: #{event.office}"
+    puts
+  end
+
+rescue PocztaPolska::UnknownPackageError
+  puts "The package couldn't be found"
+rescue PocztaPolska::WrongPackageError
+  puts "The package ID is wrong"
+end
+
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/hejmsdz/poczta_polska.rb/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "poczta_polska"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/examples/example.rb

@@ -0,0 +1,26 @@
+require 'poczta_polska'
+
+package_id = 'testp0'
+# this package ID generates test data
+
+tr = PocztaPolska::tracker
+
+begin
+  pkg = tr.check(package_id)
+
+  puts "A package was sent from #{pkg.office_from} to #{pkg.office_to}."
+
+  pkg.events.each do |event|
+    datetime = event.time.strftime("%F, %R")
+    puts "Finally:" if event.final?
+    puts "Time: #{datetime}"
+    puts "Event: #{event.name}"
+    puts "Post office: #{event.office}"
+    puts
+  end
+
+rescue PocztaPolska::UnknownPackageError
+  puts "The package couldn't be found"
+rescue PocztaPolska::WrongPackageError
+  puts "The package ID is wrong"
+end

data/lib/poczta_polska.rb

@@ -0,0 +1,29 @@
+require "poczta_polska/version"
+
+module PocztaPolska
+
+  Error = Class.new(RuntimeError)
+  UnknownPackageError = Class.new(Error)
+  WrongPackageError = Class.new(Error)
+  TooManyPackagesError = Class.new(Error)
+  ManyPackagesForbiddenError = Class.new(Error)
+  DateRangeError = Class.new(Error)
+
+  # Creates a Tracker instance. Authentication is optional,
+  # it will allow you to check multiple packages in a single request.
+  # @param username [String]
+  # @param password [String]
+  # @return [Tracker] a Tracker instance
+  def self.tracker(username = nil, password = nil)
+    if username.nil? && password.nil?
+      Tracker.new('https://tt.poczta-polska.pl/Sledzenie/services/Sledzenie?wsdl', 'sledzeniepp', 'PPSA')
+    else
+      Tracker.new('https://ws.poczta-polska.pl/Sledzenie/services/Sledzenie?wsdl', username, password)
+    end
+  end
+
+  require "poczta_polska/tracker"
+  require "poczta_polska/package"
+  require "poczta_polska/office"
+  require "poczta_polska/event"
+end

data/lib/poczta_polska/dynamic_reader.rb

@@ -0,0 +1,34 @@
+module PocztaPolska
+  # This helper module is +include+d into other classes
+  # and allows to access elements nested in the +@data+ hash.
+  # In order to use it, a class must define a constant hash +ATTR_MAP+.
+  # For the following element in the hash:
+  #
+  # +my_method: [:some, :nested, :value, :to_s]+
+  #
+  # calling +object.my_method+ will return @data[:some][:nested][:value].to_s.
+  # The last element in the array is either a conversion method name, a +Proc+ or +nil+.
+  module DynamicReader
+    # Returns +true+ if the method name is a key in the +ATTR_MAP+ hash.
+    def respond_to_missing?(method, include_private = false)
+      self.class::ATTR_MAP.has_key?(method) || super
+    end
+
+    def method_missing(method)
+      return super unless respond_to_missing?(method)
+
+      keys = self.class::ATTR_MAP[method].dup
+      convert = keys.pop
+      d = @data
+      keys.each { |k| d = d[k] }
+
+      if convert.nil?
+        d
+      elsif convert.is_a?(Proc)
+        convert.call(d)
+      else
+        d.public_send(convert)
+      end
+    end
+  end
+end

data/lib/poczta_polska/event.rb

@@ -0,0 +1,45 @@
+require 'poczta_polska/dynamic_reader'
+require 'poczta_polska/office'
+
+module PocztaPolska
+  # The Event class stores information about a point
+  # on the package's way.
+  class Event
+    # @return [Hash] Original data from the XML response
+    attr_reader :data
+
+    # Dynamic methods map
+    # @see DynamicReader
+    ATTR_MAP = {
+      time: [:czas, lambda { |time| DateTime.parse(time) }],
+      code: [:kod, :to_sym],
+      name: [:nazwa, :to_s],
+      office: [:jednostka, :nazwa, :to_s],
+      final?: [:konczace, nil]
+    }
+    include DynamicReader
+
+    def initialize(data)
+      @data = data
+    end
+
+    # Returns detailed information about the post office connected with this event,
+    # only if the {Tracker#check}/{Tracker#check_many} method was called
+    # with +details+ set to +true+.
+    # @return [Office]
+    def office_details
+      office = @data[:jednostka][:dane_szczegolowe]
+      Office.new(office) unless office.nil?
+    end
+
+    # Returns a reason of the event (available only for certain events
+    # and certain users) or +nil+. The keys in the hash are +:code+ and +:name+.
+    # @return [Hash]
+    def reason
+      {
+        code: @data[:przyczyna][:kod].to_sym,
+        name: @data[:przyczyna][:nazwa].to_s
+      } unless @data[:przyczyna].nil?
+    end
+  end
+end

data/lib/poczta_polska/office.rb

@@ -0,0 +1,48 @@
+module PocztaPolska
+  # The Office class stores detailed information about
+  # a particular post office.
+  class Office
+    # @return [Hash] Original data from the XML response
+    attr_reader :data
+
+    def initialize(data)
+      @data = data
+    end
+
+    # Returns geographical coordinates of the post office.
+    # @return [Array(Float, Float)] latitude and longitude
+    def coordinates
+      [@data[:szer_geogr].to_f, @data[:dl_geogr].to_f]
+    end
+
+    # Returns the address of the post office.
+    # The keys in the hash are +:street+, +:number+, +:code+ and +:town+.
+    # @return [Hash]
+    def address
+      {
+        street: @data[:ulica].to_s,
+        number: @data.values_at(:nr_domu, :nr_lokalu).compact.join('/'),
+        code: @data[:pna].to_s,
+        town: @data[:miejscowosc].to_s
+      }
+    end
+
+    # Returns opening hours of the post office.
+    # The keys in the hash are +:weekdays+, +:saturdays+ and +:sundays+ (including holidays).
+    # Every value is an array in the format +[opening_hours, notes]+ or +nil+.
+    # @return [Hash<Symbol => Array(String, String), nil>]
+    def opening_hours
+      hours = @data[:godziny_pracy]
+      keys = {weekdays: :dni_robocze, saturdays: :soboty, sundays: :niedz_i_sw}
+      Hash[
+        keys.map do |h, x|
+          value = unless hours[x].nil?
+            [hours[x][:godziny].to_s, hours[x][:uwagi].to_s]
+          end
+
+          [h, value]
+        end
+      ]
+    end
+  end
+end

data/lib/poczta_polska/package.rb

@@ -0,0 +1,58 @@
+require 'poczta_polska/dynamic_reader'
+require 'poczta_polska/office'
+require 'poczta_polska/event'
+
+module PocztaPolska
+  # The Package class contains all necessary information
+  # about a tracked package.
+  class Package
+    # @return [Hash] Original data from the XML response
+    attr_reader :data
+
+    # Dynamic methods map
+    # @see DynamicReader
+    ATTR_MAP = {
+      id: [:numer, :to_s],
+      type: [:dane_przesylki, :kod_rodz_przes, :to_sym],
+      type_str: [:dane_przesylki, :rodz_przes, :to_s],
+      country_from: [:dane_przesylki, :kod_kraju_nadania, :to_sym],
+      country_from_str: [:dane_przesylki, :kraj_nadania, :to_s],
+      country_to: [:dane_przesylki, :kod_kraju_przezn, :to_sym],
+      country_to_str: [:dane_przesylki, :kraj_przezn, :to_s],
+      office_from: [:dane_przesylki, :urzad_nadania, :nazwa, :to_s],
+      office_to: [:dane_przesylki, :urzad_przezn, :nazwa, :to_s],
+      mass: [:dane_przesylki, :masa, nil],
+      ready?: [:dane_przesylki, :zakonczono_obsluge, nil]
+    }
+    
+    include DynamicReader
+
+    def initialize(data)
+      @data = data
+    end
+
+    # Returns detailed information about the origin post office,
+    # only if the {Tracker#check}/{Tracker#check_many} method was called
+    # with +details+ set to +true+.
+    # @return [Office]
+    def office_from_details
+      office = @data[:dane_przesylki][:urzad_nadania][:dane_szczegolowe]
+      Office.new(office) unless office.nil?
+    end
+
+    # Returns detailed information about the destination post office,
+    # only if the {Tracker#check}/{Tracker#check_many} method was called
+    # with +details+ set to +true+.
+    # @return [Office]
+    def office_to_details
+      office = @data[:dane_przesylki][:urzad_przezn][:dane_szczegolowe]
+      Office.new(office) unless office.nil?
+    end
+
+    # Returns a list of all events connected with the package
+    # @return [Array<Event>]
+    def events
+      @data[:dane_przesylki][:zdarzenia][:zdarzenie].map { |e| Event.new(e) }
+    end
+  end
+end

data/lib/poczta_polska/tracker.rb

@@ -0,0 +1,87 @@
+require 'savon'
+
+module PocztaPolska
+  # The Tracker class gives access to all necessary API methods
+  # and wraps the results in correct Ruby classes.
+  class Tracker
+    def initialize(wsdl, username, password)
+      @client = Savon.client(wsdl: wsdl, wsse_auth: [username, password])
+    end
+
+    # Returns the API version you are using.
+    def api_version
+      resp = @client.call(:wersja)
+      resp.body[:wersja_response][:return].to_s
+    end
+
+    # Returns the maximum number of packages that you can
+    # check in a single request with {#check_many} method.
+    # If you are not authenticated, it is always 1.
+    def max_packages
+      resp = @client.call(:maksymalna_liczba_przesylek)
+      resp.body[:maksymalna_liczba_przesylek_response][:return].to_i
+    end
+
+    # Finds a package by its ID.
+    # @param package_id [String] the ID of a package to find
+    # @param details [Boolean] whether to include detailed information (location, opening hours) about the post offices involved
+    # @return [Package] information about the package
+    # @raise [UnknownPackageError] if the package couldn't be found
+    # @raise [WrongPackageError] if the package ID is invalid
+    # @raise [Error] if something else goes wrong
+    def check(package_id, details = false)
+      method_name = 'sprawdz_przesylke'
+      method_name << '_pl' if details
+
+      method = method_name.to_sym
+      response_key = "#{method_name}_response".to_sym
+
+      response = @client.call(method, message: {numer: package_id})
+      data = response.body[response_key][:return]
+
+      case data[:status].to_i
+      when -1 then raise UnknownPackageError
+      when -2 then raise WrongPackageError
+      when -99 then raise Error
+      end
+
+      Package.new(data)
+    end
+
+    # Finds multiple packages by their IDs.
+    # @param package_ids [Array<String>] IDs of the packages to find
+    # @param details [Boolean] whether to include detailed information (location, opening hours) about the post offices involved
+    # @param date_range [Range<Date>] narrow the list down so that it only includes packages with events in the specified date range
+    # @return [Array<Package>] information about the packages found
+    # @raise [TooManyPackagesError] if you exceed the limit of packages you can check in a single request ({#max_packages})
+    # @raise [ManyPackagesForbiddenError] if you are not authenticated, so you can't check many packages at once
+    # @raise [DateRangeError] if the date range specified is invalid
+    # @raise [Error] if something else goes wrong
+    def check_many(package_ids, details = false, date_range = nil)
+      method_name = 'sprawdz_przesylki'
+      method_name << '_od_do' unless date_range.nil?
+      method_name << '_pl' if details
+
+      method = method_name.to_sym
+      response_key = "#{method_name}_response".to_sym
+
+      params = {numery: package_ids}
+      unless date_range.nil?
+        params[:od_dnia] = date_range.first.iso8601
+        params[:do_dnia] = date_range.end.iso8601
+      end
+
+      response = @client.call(method, message: params)
+      data = response.body[response_key][:return]
+
+      case data[:status].to_i
+      when -1 then raise TooManyPackagesError
+      when -2 then raise ManyPackagesForbiddenError
+      when -3 then raise DateRangeError
+      when -99 then raise Error
+      end
+
+      data[:przesylki].map { |p| Package.new(p) }
+    end
+  end
+end

data/lib/poczta_polska/version.rb

@@ -0,0 +1,3 @@
+module PocztaPolska
+  VERSION = "0.1.0"
+end

data/poczta_polska.gemspec

@@ -0,0 +1,43 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'poczta_polska/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "poczta_polska"
+  spec.version       = PocztaPolska::VERSION
+  spec.authors       = ["Mikołaj Rozwadowski"]
+  spec.email         = ["mikolaj.rozwadowski@outlook.com"]
+
+  spec.summary       = "Track Polish Post packages in Ruby"
+  spec.description   = "With this gem you can monitor Polish Post parcels and registered mail "
+                       "as well as packages shipped by Pocztex. It allows you to see basic data "
+                       "about the consignment as well as all the post offices it has gone through "
+                       "(including their locations and opening hours). The data is downloaded from "
+                       "[a public SOAP API of the Polish Post](http://www.poczta-polska.pl/pliki/webservices/"
+                       "Metody%20i%20struktury%20uslugi%20sieciowej%20Poczty%20Polskiej%20SA.pdf) "
+                       "and wrapped into Ruby classes for your convenience."
+  spec.homepage      = "https://github.com/hejmsdz/poczta_polska.rb"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
+  # delete this section to allow pushing this gem to any host.
+  # if spec.respond_to?(:metadata)
+  #   spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+  # else
+  #   raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  # end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "savon", "~> 2.11", ">= 2.11.1"
+  spec.add_dependency "rubyntlm", "~> 0.5"
+
+  spec.add_development_dependency "bundler", "~> 1.9"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.3"
+  spec.add_development_dependency "yard", "~> 0.8"
+end

metadata

@@ -0,0 +1,153 @@
+--- !ruby/object:Gem::Specification
+name: poczta_polska
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mikołaj Rozwadowski
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-06-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: savon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.11'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.11.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.11'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.11.1
+- !ruby/object:Gem::Dependency
+  name: rubyntlm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: 'With this gem you can monitor Polish Post parcels and registered mail '
+email:
+- mikolaj.rozwadowski@outlook.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- examples/example.rb
+- lib/poczta_polska.rb
+- lib/poczta_polska/dynamic_reader.rb
+- lib/poczta_polska/event.rb
+- lib/poczta_polska/office.rb
+- lib/poczta_polska/package.rb
+- lib/poczta_polska/tracker.rb
+- lib/poczta_polska/version.rb
+- poczta_polska.gemspec
+homepage: https://github.com/hejmsdz/poczta_polska.rb
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Track Polish Post packages in Ruby
+test_files: []
+has_rdoc: