prioticket 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a8270ce77d4f2db94fbdd7ba0393af31199f9863
+  data.tar.gz: 496fdc625a0d8006ed9734bed00e055d108e5028
+SHA512:
+  metadata.gz: 55f87f2ad13a09ed5ad7f9e08636f7f7b5a7f26b4dcea6b078e4758eb16b17a0e74342a6be42670b2a2f2ea988a71d8ac6c7a004c490f5a5f35a15ec8ccd3a10
+  data.tar.gz: 11d934e649cb210de50288c330f7a73355400579760f1f0b2626c2592b5bab68e31a254a04175904139e41c3ffce129a0187a726bbb8ddd6e913894564acbf52

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,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.2.3
+before_install: gem install bundler -v 1.13.6

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Henk Meijer
+
+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,213 @@
+# PrioTicket
+[![Gem Version](https://badge.fury.io/rb/prioticket.svg)](https://badge.fury.io/rb/prioticket)
+[![Dependency Status](https://gemnasium.com/henkm/prioticket.svg)](https://gemnasium.com/henkm/prioticket)
+[![Code Climate](https://codeclimate.com/github/henkm/prioticket/badges/gpa.svg)](https://codeclimate.com/github/henkm/prioticket)
+
+This gem works as a simple Ruby wrapper for the PrioTicket API. All the API functions are implemented.
+
+Instead of working with JSON, you work with Ruby Classes and intuitive methods.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'prioticket'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install prioticket
+
+## Configuration
+
+First, obtain an API key from PrioTicket. Set it up like this:
+```ruby
+PrioTicket::Config.api_key      = "MY-API-KEY"
+PrioTicket::Config.environment  = "test"
+```
+
+To use this gem in a Rails project:
+```ruby
+# config/development.rb
+config.prioticcket.api_key      = "MY-API-KEY"
+config.prioticcket.environment  = "test"
+```
+
+## Usage
+The available classes and methods are listed below. General rule of thumb: all the naming is 100% consistant with the official API Documentation. So use `PrioTicket::Booking.new(booking_name: 'John Doe', booking_email: 'john@example.net')` instead of using the more intuitive `PrioTicket::Booking.new(name: 'John Doe', email: 'john@example.com')`
+
+**Important**: the `Reservation` and `Booking` classes will only create a new reservation/booking in memory, when initialized (e.g. `Reservation.new(...)`). To submit it to the server, call `save`.
+
+### TicketList
+To list the available tickets, call:
+```ruby
+@ticket_list = PrioTicket::TicketList.find(distributor_id: 1234, identifier: "my-unique-order-abc-123")
+# Returns an object with a method `tickets`, which returns an array of tickets:
+# => <PrioTicket::TicketList @tickets=[##<PrioTicket::Ticket @ticket_id=362, @ticket_title="100 Highlights  Cruise", @venue_name="Stromma Nederland", @txt_language="zh,ru,pt,nl,it,fr,de,es,en">, etc...]>
+```
+
+### TicketDetails
+There are two ways to collect detailed information about a Ticket from the TicketList:
+
+#### Find them using the `find` method
+
+```ruby
+@ticket_details = PrioTicket::TicketDetails.find(distributor_id: 1234, ticket_id: 123, identifier: "my-unique-order-abc-123")
+# => <PrioTicket::TicketDetails @ticket_id=1234, @ticket_title="100 Highlights  Cruise", @short_description="The No.1 Amsterdam canal cruise", etc...> 
+```
+
+#### Collect them via the parent object
+```ruby
+@ticket_list = PrioTicket::TicketList.find(distributor_id: 1234, identifier: "my-unique-order-abc-123")
+@ticket_details = @ticket_list.first.ticket_details
+# => <PrioTicket::TicketDetails @ticket_id=1234, @ticket_title="100 Highlights  Cruise", @short_description="The No.1 Amsterdam canal cruise", etc...> 
+```
+
+So to get the tags from a certain TicketDetails, you can call:
+```ruby
+@ticket_list.first.ticket_details.tags
+# => ["Students", "Wheelchair accessible"]
+```
+or:
+```ruby
+@ticket_list.first.ticket_details.company_opening_times.first.start_from
+# => "09:00:00"
+
+```
+
+### Availabilities
+The same goes for fetching availabilities:
+```ruby
+  @availabilities = PrioTicket::Availabilities.find(distributor_id: 1234, ticket_id: 123, identifier: "my-unique-order-abc-123", from_date: Time.now, until_date: Time.now+(60*60*24*7))
+  # or:
+  @availabilities = @ticket_details.availabilities(from_date: Time.now, until_date: Time.now+(60*60*24*7))
+```
+
+### Reservation
+To reserve a date, use the `PrioTicket::Reservation` class:
+```ruby
+@reservation = PrioTicket::Reservation.new(
+  identifier: "my-unique-order-abc-123",
+  distributor_id: 1234,
+  ticket_id: 123,
+  from_date_time: @availabilities.first.from_date_time,
+  to_date_time: @availabilities.first.to_date_time,
+  booking_details: [{ticket_type: "ADULT", count: 1}],
+  distributor_reference: "TEST_RESERVATION"
+)
+# at this point, the reservation is only made in memory, but not yet
+# send to the PrioTicket server. To make in final, call `save`.
+
+@reservation.save
+# => #<PrioTicket::Reservation @identifier="test-1522067114", @distributor_id=1234, @ticket_id=123, @from_date_time="2018-03-26T23:00:00+02:00", @to_date_time="2018-03-26T23:59:00+02:00", @booking_details=[#<OpenStruct ticket_type="ADULT", count=1>], @distributor_reference="TEST_RESERVATION", @booking_status="Reserved", @reservation_reference="YYY2067115376XXX">
+
+# Cancel this reservation:
+@reservation.cancel
+@reservation.booking_status #=> "Cancelled"
+```
+
+### Booking
+To make a booking, please take note of the official API Documentation: for tickets of type_2 and type_3, a `from_date_time` and `to_date_time` must be present. 
+
+Example code in section below.
+
+## Full example
+All the steps are combined in the example below:
+1. Setup the API credentials
+2. Get a list of all the tickets/products
+3. Find out details of a specific ticket
+4. Get availability
+5. Make a booking
+6. Get status / cancel booking
+
+```ruby
+
+# step 1
+# config/development.rb (in case of Ruby on Rails App)
+config.prioticcket.api_key      = "MY-API-KEY"
+config.prioticcket.environment  = "test"
+
+# Code below goes in a controller or model, handling the application logic
+
+# step 2
+@ticket_list = PrioTicket::TicketList.find(distributor_id: 1234, identifier: "test-123")
+
+# step 3
+@ticket = @ticket_list.tickets.first.details
+#=> <PrioTicket::TicketDetails> includes name, prices, etc.
+
+# step 4
+# method defaults to 3 weeks ahead, you can provice from_date_time and to_date_time
+@available_times = @ticket.availabilities
+
+# step 5 - book first available time
+@booking = PrioTicket::Booking.new(
+  identifier: "test-123",
+  distributor_id: 1234,
+  booking_type: {
+    ticket_id: @ticket.ticket_id,
+    booking_details: [{
+      ticket_type: "ADULT",
+      count: 2,
+      extra_options: []
+    }]
+  },
+  booking_name: "John Doe",
+  booking_email: "john@example.com",
+  contact: {
+    address: {
+      street: "Amstel 1",
+      postal_code: "1011 PN",
+      city: "Amsterdam"
+    },
+    phonenumber: "0643210123"
+  },
+  notes: ["This is a test booking"],
+  product_language: "en",
+  distributor_reference: "ABC123456"
+)
+
+# the booking is now made in memory, but not yet final
+@booking.confirmed?
+# => false
+
+@booking.save
+# => <PrioTicket::Booking> object, with status and barcodes
+
+@booking.confirmed?
+# => true
+
+@booking.cancel
+@booking.confirmed?
+# => false
+@booking.canceled?
+# => true
+
+@booking.booking_reference # => 123ABC456XYZ
+
+# another way to ask for the status of a booking:
+@booking = PrioTicket::Booking.get_status(
+  identifier: @booking.identifier,
+  distributor_id: DIST_ID, 
+  booking_reference: "123ABC456XYZ", 
+  distributor_reference: "ABC123456
+)
+@booking.status # => "Cancelled"
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/henkm/prioticket.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT). No rights can be derrived from using this library.
+
+This gem is made with love by the smart people at [Eskes Media B.V.](https://www.eskesmedia.nl) and [DagjeWeg.NL Tickets](https://www.dagjewegtickets.nl)
+PrioTicket is not involved with this project and has no affiliation with Eskes Media B.V.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "prioticket"
+
+# 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,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/prioticket/api.rb

@@ -0,0 +1,94 @@
+module PrioTicket
+
+  # The communication layer implements all the methods available in the PrioTicket API
+  # NOTE: You need to request access to view the documentation.
+  # https://support.prioticket.com/docs/
+  class API
+
+    # 
+    # Returns the API endpoint to use
+    # 
+    # @return [type] [description]
+    def self.endpoint
+      if PrioTicket::Config.environment.to_s == "test"
+        "https://test-api.prioticket.com/v2.4/booking_service"
+      else
+        "https://api.prioticket.com/v2.4/booking_service"
+      end
+    end
+
+    # The request authentication key will contain the following items:
+    # (a) API Key Token
+    # (b) Request Identifier
+    # 
+    # The API Key Token information for the TEST and LIVE environment will be sent in a separate mail. 
+    # The Request Identifier should be an unique string generated by the initiator. Common examples are 
+    # a timestamp, booking reference or UUID.The request authentication key will be computed per request 
+    # as follows: 
+    # 
+    def self.request_authentication_key(request_identifier="")
+      # 1. Create a string with format <x-request-identifier>:<apikeytoken> where x-request-identifier 
+      #    and apikeytoken are respective strings.
+      step_1_string = "#{request_identifier}:#{Config.api_key}"
+
+      # 2. Convert the string from step 1 to byte array using UTF-8 encoding.
+      step_2_string = step_1_string.encode('utf-8')
+
+      # 3. Compute the SHA-256 hash for the byte array from step 2. The result will be a byte array.
+      step_3_string = Digest::SHA256.digest(step_2_string).strip
+      
+      # 4. Base64 encode the byte array as computed in step 3. 
+      #    This string will be the x-request-authentication key for this request.
+      step_4_string = Base64.encode64(step_3_string).strip
+
+      return step_4_string
+    end
+
+    # 
+    # Computes the request header
+    # @param request_identifier="" [type] A unique request identifier, 
+    # e.g. timestamp order_id, booking_reference or UUID.
+    # 
+    # @return [Hash] the header details for API calls
+    def self.request_header(request_identifier="")
+      { 
+        content_type: "application/json", 
+        x_request_authentication: request_authentication_key(request_identifier), 
+        x_request_identifier: request_identifier
+      }
+    end
+    
+
+    # 
+    # Makes a HTTP POST call to the endpoint en returns the response
+    # 
+    # @param request_body [type] [description]
+    # @param request_identifier [type] [description]
+    # 
+    # @return OpenStruct object with nested methods.
+    def self.call(request_body, request_identifier, verbose=false)
+      values   = request_body.to_json
+      headers  = request_header(request_identifier)
+      if verbose || PrioTicket::Config.verbose == true
+        puts "Calling with:"
+        puts "Identifier: #{request_identifier}"
+        puts "Header: #{headers.to_json}"
+        puts "Body: #{values}"
+        puts "Endpoint: #{endpoint}"
+      end
+      raise PrioTicketError.new "Request Identifier is not present, please provide an @identifier" if request_identifier.nil? || request_identifier == ''
+      begin
+        response = RestClient.post endpoint, values, headers
+      rescue RestClient::ExceptionWithResponse => e
+        if verbose || PrioTicket::Config.verbose == true
+          puts "Error: #{e.response}"
+        end
+        error_json = JSON.parse(e.response)
+        message = "#{error_json["error_message"]} (#{error_json["error_code"]}) - #{e}"
+        raise PrioTicketError.new message
+      end
+      object   = JSON.parse(response.body)
+      return object
+    end
+  end
+end

data/lib/prioticket/availabilities.rb

@@ -0,0 +1,89 @@
+module PrioTicket
+
+  # This endpoint should be called in order to get up-to-date availability 
+  # information for a product with managed capacity. The response will contain
+  # the availability for each time slot of the requested product that lies within
+  # the specified date range. Time slots will not be omitted in case of no availability. 
+  # Neither will a NO_AVAILABILITY error be returned in that case. 
+  # Instead, an explicit vacancy of zero should be expected.
+  # 
+  class Availabilities
+    attr_accessor :from_date_time
+    attr_accessor :to_date_time
+    attr_accessor :vacancies
+
+
+    def initialize(args=nil)
+      return if args.nil?
+      args.each do |k,v|
+        PrioTicket.parse_json_value(self, k,v)
+      end
+    end
+
+    # 
+    # Calls the request type 'availabilities' with given
+    # details and retruns an array of Availabilities objects
+    # 
+    # @param distributor_id Integer
+    # @return Array
+    def self.find(distributor_id: nil, ticket_id: nil, from_date: nil, until_date: nil, identifier: nil)
+      result = PrioTicket::API.call(request_body(ticket_id: ticket_id, distributor_id: distributor_id, from_date: from_date, until_date: until_date), identifier, false)
+      list = []
+      for a in result["data"]["availabilities"]
+        list << Availabilities.new(a)
+      end
+      return list
+    end
+
+    # 
+    # Computes the request body to send to the API endpoint
+    # @param distributor_id Integer
+    # @param ticket_id Integer
+    # @param from_date String
+    # @param until_date String
+    # 
+    # @return Hash
+    def self.request_body(distributor_id: nil, ticket_id: nil, from_date: nil, until_date: nil)
+      {
+        request_type: "availabilities",
+        data: {
+          distributor_id: distributor_id,
+          ticket_id: ticket_id,
+          from_date: PrioTicket.parsed_date(from_date),
+          until_date: PrioTicket.parsed_date(until_date)
+        }
+      }
+    end
+
+
+    def reserve
+      # {
+      # "request_type": "reserve",
+      # "data": {
+      # "distributor_id": "501",
+      # "ticket_id": "509",
+      # "pickup_point_id": "Wyndham_Apollo_hotel",
+      # "from_date_time": "2017-11-22T09:00:00+01:00",
+      # "to_date_time": "2017-11-23T09:00:00+01:00",
+      # "booking_details": [
+      # {
+      # "ticket_type": "ADULT",
+      # "count": 1
+      # }
+      # ],
+      # "distributor_reference": "ABC123456"
+      # }
+      # }
+
+      # {
+      # "response_type": "reserve",
+      # "data": {
+      # "reservation_reference": "123456789",
+      # "distributor_reference": "ABC123456",
+      # "booking_status": "Reserved"
+      # }
+      # }
+    end
+
+  end
+end

data/lib/prioticket/booking.rb

@@ -0,0 +1,197 @@
+module PrioTicket
+
+  # Describes a Booking
+	# This API is called to get a ticket booked and get a barcode/QR-code in response. 
+	# The booking API provides a booking reference in response.
+	# There are 5 different booking options:
+	# - Booking of ticket without timeslot (ticket_class 1).
+	# - Booking of ticket with timeslot (ticket_class 2/ticket_class 3), 
+	# 	without reservation_reference.
+	# - Booking of ticket with timeslot (ticket_class 2/ticket_class 3), 
+	# 	with reservation_reference.
+  # 
+  class Booking
+    
+    attr_accessor :identifier
+    attr_accessor :distributor_id
+    # attr_accessor :booking_type
+    attr_accessor :booking_type
+    attr_accessor :booking_name
+    attr_accessor :booking_email
+    attr_accessor :notes
+    attr_accessor :contact
+    attr_accessor :product_language
+    attr_accessor :distributor_reference
+    attr_accessor :reservation_reference
+
+
+    # contact details
+  	attr_accessor :phone_number
+  	attr_accessor :street
+  	attr_accessor :postal_code
+  	attr_accessor :city
+
+  	# completed booking attrs
+  	attr_accessor :booking_reference
+  	attr_accessor :booking_status
+  	attr_accessor :booking_details
+
+    def initialize(args)
+      return if args.nil?
+      args.each do |k,v|
+        PrioTicket.parse_json_value(self, k,v)
+      end
+    end
+
+    # 
+    # Sends the reservation request tot the API
+    # 
+    def save
+      request_booking
+    end
+
+
+    def canceled
+      booking_status == "Cancelled"
+    end
+    alias_method :canceled?, :canceled
+
+
+    def success
+    	booking_status == "Confirmed"
+    end
+    for meth in [:success?, :confirmed, :confirmed?]
+	    alias_method meth, :success
+	  end
+
+
+    # Fetches information from ticket_details,
+    # to validate the input for this booking.
+    # e.g. if ticket_type == 2, from/to date are required.
+    # 
+    # @return [type] [description]
+    def ticket
+      begin
+        @ticket ||= PrioTicket::TicketDetails.find(distributor_id: distributor_id, ticket_id: booking_type['ticket_id'], identifier: identifier)
+      rescue
+        false
+      end
+    end
+
+
+    # 
+    # Cancels a Booking
+    # 
+    # @return Booking
+    def self.cancel(distributor_id: nil, booking_reference: nil, distributor_reference: nil, identifier: nil)
+      body = {
+        request_type: "cancel_booking",
+        data: {
+          distributor_id: distributor_id,
+          booking_reference: booking_reference,
+          distributor_reference: booking_reference  
+        }
+      }
+      result = PrioTicket::API.call(body, identifier)
+      booking = PrioTicket::Booking.new(result["data"])
+      return booking
+    end
+
+    # 
+    # Gets the status from a Booking
+    # 
+    # @return Booking
+    def self.get_status(distributor_id: nil, booking_reference: nil, distributor_reference: nil, identifier: nil)
+      body = {
+        request_type: "booking_status",
+        data: {
+          distributor_id: distributor_id,
+          booking_reference: booking_reference,
+          distributor_reference: booking_reference  
+        }
+      }
+      result = PrioTicket::API.call(body, identifier)
+      booking = PrioTicket::Booking.new(result["data"])
+      return booking
+    end
+
+    private
+
+    # 
+    # Sends the reservation request to the API endpoint
+    # and enriches current object with status and reference.
+    # 
+    def request_booking
+      result = PrioTicket::API.call(request_body, identifier)
+      parse_result(result)
+    end
+
+
+    # 
+    # Computes the details to send to the API
+    # 
+    # @return Hash
+    def request_body
+      for att in [:distributor_id, :booking_type, :booking_name, :booking_email, :contact, :notes, :product_language, :distributor_reference]
+        raise PrioTicketError.new("Booking is missing attribute `#{att}` (Hash)") unless send(att)
+      end
+      body = {
+        request_type: "booking",
+        data: {
+        	distributor_id: distributor_id,
+        	booking_type: validated_booking_type_hash,
+        	booking_name: booking_name,
+        	booking_email: booking_email,
+        	contact: PrioTicket.openstruct_to_hash(contact).to_h,
+        	notes: notes.to_a,
+        	product_language: product_language,
+        	distributor_reference: distributor_reference
+        }
+      }
+      
+      # add pickuppoint to body, if present
+      # body[:data][:pickup_point_id] = pickup_point_id if pickup_point_id
+      return body
+    end
+
+    # 
+    # Calculates and validates the information for 'booking_type'
+    # 
+    # @return Hash
+    def validated_booking_type_hash
+      
+      # loops through all the booking details and raises error 
+      # if from/to date_time are not present.
+      if ticket
+        if [2,3].include?(ticket.ticket_class)
+          unless booking_type.from_date_time && booking_type.to_date_time
+            err_msg = "The `booking_type` attribute requires a from_date_time and to_date_time for a ticket of ticket_class #{ticket.ticket_class}."
+            raise PrioTicketError.new(err_msg)
+          end
+        end
+      end
+      data = {}
+
+      data[:ticket_id]              = booking_type.ticket_id unless booking_type.reservation_reference
+      data[:booking_details]        = booking_type.booking_details.map{|bd| PrioTicket.openstruct_to_hash(bd)} unless booking_type.reservation_reference
+      data[:reservation_reference]  = booking_type.reservation_reference if booking_type.reservation_reference
+      
+      if booking_type.from_date_time && booking_type.to_date_time
+        data[:from_date_time] = booking_type.from_date_time
+        data[:to_date_time]   = booking_type.to_date_time
+      end
+      return data
+    end
+
+    # 
+    # Parses the return value from the API
+    # 
+    def parse_result(result)
+      self.booking_status     = result["data"]["booking_status"]
+      self.booking_reference	= result["data"]["booking_reference"]
+      PrioTicket.parse_json_value(self, :booking_details, result["data"]["booking_details"])
+    end
+
+
+	end
+end