caren-api 0.2.0 → 0.3.0

data/README.rdoc

@@ -2,14 +2,37 @@
 
 This is the reference implementation for the Caren CareProvider API (http://caren-cares.com). 
 
-To get started you will need a care provider API shared key. Set `Caren::Api.shared_key` to the key file.
+== Getting started
 
-Generate a private key using: `openssl genrsa -out example 1024`
-Then extract the public key from it: `openssl rsa -in example -pubout -out example.pub`
-Send the public key to info@caren-cares.com with an access request.
+To get started you will need a care provider API private/public keypair.
 
-Next you will need to set your care provider url `Caren::Api.url` to your specific URL like https://example.caren-cares.com. 
-This url will be provided.
+* Generate a private key using: `openssl genrsa -out example 1024`
+* Extract the public key from it: `openssl rsa -in example -pubout -out example.pub`
+* Send the public key to info@caren-cares.com with an access request.
+* Set your care provider url `Caren::Api.url` to the provided URL like https://example.caren-cares.com. 
+
+== Getting information from Caren
+
+This implementation shows you how to get information from Caren. You can gather information about Links (linking your people to caren's),
+care_providers (including updating your settings) and external_messages (chat messages between you and caren people).
+
+== Providing information to Caren
+
+Some information you can push to Caren (like updates to care_provider settings and new messages) using the basic API. 
+Additionally Caren requires you to provide XML resources for People (search) and Events (daterange).
+You can specify your API base url within your care_provider settings. You are required to implement the following resources:
+
+* Finding a person by identifier: GET [BASE_URL]/people/?uid=[VALUE]
+* Finding a list of events for a given person: GET [BASE_URL]/people/[EXTERNAL_ID]/events?from=[DATE]&to=[DATE]
+
+The uid is your public customer number for this person, the external_id is your internal identifier (usually database id) for this person.
+These urls should yield Caren compatible XML (the included Caren objects for Event and Person can generate that for you)
+
+== Push notifications of changes from Caren
+
+Caren supports a push link. Caren will regularly post a XML file with changes (Links, CareProviders, ExternalMessages) to any url.
+Passing this XML and the corresponsing header signature into `Caren::Api.incoming` will yield the updated Caren objects.
+You can optionally specify a push url within your care_provider settings.
 
 == Contributing to caren-api
  

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/caren-api.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{caren-api}
-  s.version = "0.2.0"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Andre Foeken"]
@@ -50,6 +50,7 @@ Gem::Specification.new do |s|
     "spec/fixtures/caren_links.xml",
     "spec/fixtures/caren_links_search.xml",
     "spec/fixtures/caren_unauthorized.xml",
+    "spec/fixtures/incoming.xml",
     "spec/link_spec.rb",
     "spec/person_spec.rb",
     "spec/spec.opts",

data/lib/caren/base.rb

@@ -11,8 +11,10 @@ class Caren::Base
     self.class.keys.each do |key|
       self.attributes[key] = args[key] || args[key.to_s] || nil
     end
+    # We want to use #id
+    self.instance_eval('undef id')
   end
-  
+    
   # List of available attributes for this object
   def self.keys
     []

data/lib/caren/care_provider.rb

@@ -5,7 +5,7 @@
 class Caren::CareProvider < Caren::Base
       
   def self.keys
-    [ :caren_id,                    # String (The id of this CP inside Caren)
+    [ :id,                          # String (The id of this CP inside Caren)
       :name,                        # String
       :telephone,                   # String
       :website,                     # String
@@ -19,7 +19,9 @@ class Caren::CareProvider < Caren::Base
       :max_start,                   # String (23:00)
       :min_start,                   # String (07:00)
       :show_employee_name_as_title, # Boolean
-      :communication                # Boolean
+      :communication,               # Boolean
+      :push_hook_url,               # String (Optional url to push api acceptor)
+      :api_url                      # String (Required url to api resources)
     ]
   end
     
@@ -32,11 +34,11 @@ class Caren::CareProvider < Caren::Base
   end
   
   def update
-    Caren::Api.put(self.resource_url(self.caren_id), self.to_xml)
+    Caren::Api.put(self.resource_url(self.id), self.to_xml)
   end
   
   def update_logo logo_hash_or_path
-    Caren::Api.put(self.resource_url(self.caren_id), self.to_logo_xml(logo_hash_or_path))
+    Caren::Api.put(self.resource_url(self.id), self.to_logo_xml(logo_hash_or_path))
   end
     
   def as_xml

data/lib/caren/caren.rb

@@ -76,6 +76,28 @@ module Caren
       end
     end
     
+    # These types of Caren objects are supported by the Caren::Api.incoming method
+    def self.supported_incoming_objects
+      { :links => Caren::Link, 
+        :external_messages => Caren::ExternalMessage, 
+        :care_providers => Caren::CareProvider
+      }
+    end
+    
+    # Pass an XML string to be handled. Only a valid caren_objects xml hash will be parsed.
+    def self.incoming xml, signature
+      if self.verify_signature(signature,xml)
+        objects = []
+        hash = Hash.from_xml(xml)["caren_objects"]
+        self.supported_incoming_objects.each do |key,klass|
+          objects << (hash[key]||hash[key.to_s]||[]).map{ |h| klass.new(h) }
+        end
+        return objects.flatten
+      else
+        raise Caren::Exceptions::SignatureMismatch.new
+      end
+    end
+    
     # Sign your string using Caren::Api.private_key
     def self.sign string=""
       encrypted_digest = Caren::Api.private_key.sign( "sha1", string )

data/lib/caren/external_message.rb

@@ -1,12 +1,13 @@
 class Caren::ExternalMessage < Caren::Base
       
   def self.keys
-    [ :caren_id,            # String (Caren message id) 
+    [ :id,                  # String (Caren message id) 
       :person_name,         # String (Andre Foeken)
-      :external_person_id,  # String (Your person id)
+      :external_person_id,  # String (Your person id)      
       :body,                # Text
       :external_id,         # String (Your message id)
       :in_reply_to_id,      # Integer (Caren message id)
+      :in_reply_to_type,    # The type of message this is a reply to. (Always ExternalMessage if reply is set)
       :subject_id           # Integer (Caren person id)
     ]
   end
@@ -16,7 +17,7 @@ class Caren::ExternalMessage < Caren::Base
   end
   
   def delete
-    Caren::Api.delete self.class.resource_url(self.subject_id,self.caren_id)
+    Caren::Api.delete self.class.resource_url(self.subject_id,self.id)
   end
   
   def self.array_root

data/lib/caren/link.rb

@@ -1,7 +1,8 @@
 class Caren::Link < Caren::Base
       
   def self.keys
-    [:person_name,    # String (Caren person name)
+    [:id,             # String (Caren id)
+     :person_name,    # String (Caren person name)
      :person_id,      # String (Caren person id)
      :person_photo,   # String (url of photo)
      :patient_number, # String (12345)

data/spec/care_provider_spec.rb

@@ -83,11 +83,11 @@ describe "CareProvider", "REST methods" do
   end
   
   it "should be able to update a care provider" do
-    lambda{ Caren::CareProvider.new( :caren_id => 1, :name => "Test" ).update }.should_not raise_error
+    lambda{ Caren::CareProvider.new( :id => 1, :name => "Test" ).update }.should_not raise_error
   end
   
   it "should be able to update the logo for a care provider" do
-    lambda{ Caren::CareProvider.new( :caren_id => 1 ).update_logo( "spec/fixtures/bacon.jpg" ) }.should_not raise_error
+    lambda{ Caren::CareProvider.new( :id => 1 ).update_logo( "spec/fixtures/bacon.jpg" ) }.should_not raise_error
   end
   
   it "should be able to search for a specific care provider" do

data/spec/caren_spec.rb

@@ -71,4 +71,14 @@ describe "Caren", "signature checks" do
     end  
   end
   
+  it "should be able to handle incoming xml from caren" do
+    incoming = File.read "spec/fixtures/incoming.xml"
+    results  = Caren::Api.incoming(incoming, Caren::Api.sign(incoming))
+    results.should have(4).things    
+    external_messages = results.select{ |x| x.is_a?(Caren::ExternalMessage) }
+    external_messages.first.id.should == 1    
+    links = results.select{ |x| x.is_a?(Caren::Link) }
+    links.last.id.should == 3
+  end
+  
 end

data/spec/external_message_spec.rb

@@ -42,7 +42,7 @@ describe "ExternalMessage", "REST methods" do
   end
   
   it "should be able to delete an external message" do
-    lambda{ Caren::ExternalMessage.new( :subject_id => 1, :caren_id => 1 ).delete }.should_not raise_error
+    lambda{ Caren::ExternalMessage.new( :subject_id => 1, :id => 1 ).delete }.should_not raise_error
   end
   
 end

data/spec/fixtures/incoming.xml

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<caren_objects type="hash">
+  <external-messages type="array">
+    <external-message>
+      <created-at type="datetime">2011-09-09T15:14:13+02:00</created-at>
+      <body>Expecting this to work somehow ...</body>
+      <updated-at type="datetime">2011-09-09T15:14:13+02:00</updated-at>
+      <in-reply-to-id type="integer" nil="true"></in-reply-to-id>
+      <subject-id type="integer">5</subject-id>
+      <id type="integer">1</id>
+      <in-reply-to-type nil="true"></in-reply-to-type>
+      <care-provider-id type="integer">1</care-provider-id>
+      <person-id type="integer">2</person-id>
+      <person-first-name>Matthijs Langenberg</person-first-name>
+      <person-last-name></person-last-name>
+      <person-photo>http://example.com/1.png</person-photo>
+    </external-message>
+  </external-messages>
+  <links type="array">
+    <link>
+      <created-at type="datetime">2011-10-10T10:38:49+02:00</created-at>
+      <updated-at type="datetime">2011-10-10T10:40:35+02:00</updated-at>
+      <id type="integer">1</id>
+      <care-provider-id type="integer">1</care-provider-id>
+      <person-id type="integer">3</person-id>
+      <person-name>Andre Foeken</person-name>
+      <person-photo>http://example.com/1.png</person-photo>
+      <external-id>1</external-id>
+      <status>confirmed</status>
+    </link>
+    <link>
+      <created-at type="datetime">2011-10-10T10:42:42+02:00</created-at>
+      <updated-at type="datetime">2011-10-10T10:53:07+02:00</updated-at>
+      <id type="integer">2</id>
+      <care-provider-id type="integer">1</care-provider-id>
+      <person-id type="integer">3</person-id>
+      <person-name>Andre Foeken</person-name>
+      <person-photo>http://example.com/1.png</person-photo>
+      <external-id>2</external-id>
+      <status>confirmed</status>
+    </link>
+    <link>
+      <created-at type="datetime">2011-10-10T11:05:28+02:00</created-at>
+      <updated-at type="datetime">2011-10-10T11:06:44+02:00</updated-at>
+      <id type="integer">3</id>
+      <care-provider-id type="integer">1</care-provider-id>
+      <person-id type="integer">3</person-id>
+      <person-name>Andre Foeken</person-name>
+      <person-photo>http://example.com/1.png</person-photo>
+      <external-id>3</external-id>
+      <status>confirmed</status>
+    </link>
+  </links>
+</caren_objects>

data/spec/link_spec.rb

@@ -34,6 +34,7 @@ describe "Link", "REST methods" do
   it "should be find all links using the API" do
     links = Caren::Link.all
     links.should have(3).things
+    links.first.id.should == 1
     links.first.status.should == "confirmed"
     links.first.external_id.should == "1"
     links.first.person_name.should == "Andre Foeken"

metadata

@@ -4,10 +4,10 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
+  - 3
   - 0
   segments_generated: true
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Andre Foeken
@@ -191,6 +191,7 @@ files:
 - spec/fixtures/caren_links.xml
 - spec/fixtures/caren_links_search.xml
 - spec/fixtures/caren_unauthorized.xml
+- spec/fixtures/incoming.xml
 - spec/link_spec.rb
 - spec/person_spec.rb
 - spec/spec.opts