elibri_watermarking 0.4.1 → 0.4.2

data/README.md

@@ -0,0 +1,80 @@
+# Biblioteka Elibri Watermarking
+
+## Opis
+
+Biblioteka Elibri Watermarking, dostarczana jest w postaci pliku gema (dostępna na rubygems: https://rubygems.org/gems/elibri_watermarking ).
+Użycie wymaga wcześniejszego kontaktu z serwisem Elibri (kontakt@elibri.com.pl), w celu otrzymania danych dostępowych do API.
+
+## Zastosowanie
+
+Biblioteka Elibri Watermarking upraszcza operacje wykonywane na API watermarkingu Elibri, abstrahując je do operacji wykonywanych na obiekcie Rubyego.
+
+## Użycie
+
+Aby użyć biblioteki w aplikacji Ruby on Rails, do pliku Gemfile należy dodać:
+
+```gem 'elibri_watermarking```
+
+aby użyć gema, poza aplikacją rails należy go zainstalować, komendą:
+ 
+```gem install elibri_watermarking```
+
+a następnie w konsoli w której chcemy użyć biblioteki wpisujemy: 
+
+```ruby
+require 'rubygems'
+require 'elibri_watermarking'
+```
+
+Następnie musimy zainicjalizować bibliotekę, podając token i secret, otrzymane od Elibri:
+```ruby
+client = ElibriWatermarking::Client.new('token', 'secret')
+```
+
+Biblioteka daje nam do dyspozycji parę metod, odpowiadających wywołaniom metod API watermarkingu elibri:
+
+* watermark (przyjmuje parametry: identyfikator [ISBN bez myślników lub record_reference], formaty [zapisana po przecinku lista formatów do watermarkingu - najcześciej "epub,mobi"], widoczny watermark [tekst widoczny na końcu każdego rozdziału], dopisek [krótki tekst dopisany do tytułu], zwraca identyfikator transakcji, który klient zobowiązany jest zapisać i przechowywać) - wywołuje żądanie watermarku na podanym produkcie, w podanych formatach
+* deliver (przyjmuje jeden parametr: identifykator transacji [otrzymany od watermark]) - wywołuje żądanie dostarczenia zwatermarkowanego pliku do bucketu klienta na s3
+* watermark_and_deliver (przyjmuje parametry identyczne jak watermark, zwraca identyfikator transacji, który klient zobowiązany jest zapisać i przechowywać) - wywołuje watermarkowanie pliku, a następnie żąda jego dostarczenia do bucketu klienta na s3
+* retry (przyjmuje jako parametr identyfikator transakcji, zwraca identyfikator nowej transakcji) - wywołuje żądanie ponowienia watermarkingu pliku, który został już ściągnięty (uwaga - sklep jest zobowiązany do przetrzymywanie zwatermarkowanego pliku przynajmniej przez 7 dni, dopiero po tym czasie możliwe jest wywołanie retry). Watermarking wykonywany jest z identycznymi parametrami, jak poprzedni. Klient zobowiązany jest zapisać i przechowywać nowy identyfikator transakcji. Po komendzie retry, niezbędne jest wywołanie komendy deliver w celu dostarczeni pliku do bucketu s3. Uwaga! Każdą transakcję retryować mozna tylko raz - w przypadku kolejnego żądania retry, konieczne jest podanie identyfikatora transakcji otrzymanego od poprzedniej komendy retry.
+
+## Błędy
+
+Wywołanie poszczególnych metod może spowodować wywołanie jednego z następujących wyjątków:
+
+* ParametersError - do serwera zostały wysłane złe parametry
+* AuthenticationError - podany został zły token lub zły sig
+* AuthorizationError - podany klient nie ma dostępu żądanego produktu, lub ten produkt nie istnieje, lub produkt nie posiada żądanego formatu
+* ServerException - wystąpił wewnętrzny błąd serwera elibri
+* RequestExpired - podany został zbyt stary request (request ważny jest 60 sekund)
+
+Wszystkie te wyjątki, dziedziczą po klasie ElibriException, a także zawierają w treści opis błędu otrzymanego od API.
+
+## Odebranie pliku
+
+Po wywołaniu komendy deliver, plik zostaje załadowany do bucketu s3 (dane dostępowego do niego, otrzymacie Państwo podczas zakładania konta API). Sklep zobowiązany jest ściągnąć zwatermarkowany plik z bucketu s3 i przechowywać go po swojej stronie przez minimum 7 dni.
+Plik zawsze będzie nazwany zgodnie z następującą konwencją:
+
+```
+trans_id.format
+```
+
+gdzie trans_id to identyfikator transakcji w systemie elibri (otrzymany podczas zlecania watermarkingu), a format to jeden z: epub, mobi.
+
+
+Przykładowy kod umożliwiający odczytanie i zapisanie na własnym serwerze zwatermarkowanego pliku z bucketu s3:
+```ruby
+require 'rubygems'
+require 'aws-sdk'
+
+s3 = AWS::S3.new(:access_key_id => 'amazon access key', :secret_access_key => 'amazon secret key')
+File.open('ścieżka do pliku docelowego na serwerze', 'w') do |f|
+  f.puts s3.buckets['nazwa bucketu otrzymana przy rejestracji'].objects["identyfikator transacji.żądany format"].read
+end
+```
+
+## Powiadomienie o dostępności pliku
+
+Po wykonaniu polecenia deliver, plik zostanie umieszczony w buckecie s3. Sklep zostanie powiadomiony o tym fakcie, za pomocą requestu na podany przez niego endpoint.
+
+Request jest typu post, zawiera w swojej treści identyfikator ukończonej transakcji - po jego otrzymaniu sklep powinien odebrać plik z bucketu s3 i zapisać go u siebie na serwerze.

data/lib/elibri_watermarking/client.rb

@@ -81,6 +81,8 @@ module ElibriWatermarking
         raise AuthorizationError.new(res.body)
       when "Net::HTTPInternalServerError"
         raise ServerException.new(res.body)
+      when "Net::HTTPRequestTimeOut"
+        raise RequestExpired.new(res.body)
       when "Net::HTTPOK"
         return res.body
       end

data/lib/elibri_watermarking/exceptions.rb

@@ -18,5 +18,8 @@ module ElibriWatermarking
   class WrongFormats < ElibriException
   end
   
+  class RequestExpired < ElibriException
+  end
+  
   
 end

data/lib/elibri_watermarking/version.rb

@@ -1,3 +1,3 @@
 module ElibriWatermarking
-  VERSION = "0.4.1"
+  VERSION = "0.4.2"
 end

metadata

@@ -1,48 +1,42 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: elibri_watermarking
-version: !ruby/object:Gem::Version 
-  hash: 13
+version: !ruby/object:Gem::Version
+  version: 0.4.2
   prerelease: 
-  segments: 
-  - 0
-  - 4
-  - 1
-  version: 0.4.1
 platform: ruby
-authors: 
+authors:
 - Piotr Szmielew
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-07-30 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-08-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rake
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id001
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Gem designed to help in use of Elibri watermarking API.
-email: 
+email:
 - p.szmielew@ava.waw.pl
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - Gemfile
+- README.md
 - Rakefile
 - elibri_watermarking.gemspec
 - lib/elibri_watermarking.rb
@@ -51,36 +45,26 @@ files:
 - lib/elibri_watermarking/version.rb
 homepage: http://elibri.com.pl
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: elibri_watermarking
-rubygems_version: 1.8.21
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Gem designed to help in use of Elibri watermarking API.
 test_files: []
-