stbaldricks 4.3.2.alpha.2 → 4.3.2.alpha.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ef908b5c141cd2bf03331174a10b6ccf4e155689
-  data.tar.gz: 764cc9475e5afac35f4627209de0241f0be504f7
+SHA256:
+  metadata.gz: e7ebf05a1a594e783ea1d0a2e197218f6ed3db74ce3bbf66347fb163900f2031
+  data.tar.gz: 3bc73caf5de5a61ced06fc71fbc58f08fc83834c246f278f1d07d8e4d8b534bb
 SHA512:
-  metadata.gz: ca151c0b8fef81fc77b27477d4d523d24ed42cb35643725f854ae562db315fd0ae6950dcff2c84fda7bce3ac8a366ce2a58645a2f18d9797678250761be6f899
-  data.tar.gz: 86a5c59a61aaf63c451097bf54ec9d3b53b49435cc8b0f459da980f7b68a642990d877933913e3872fd7ef100e9e450856b3ce18c266aedc5dc84d8281f0487b
+  metadata.gz: 4395a6188163ccdcf14582c7f1d096fcf4b91e9c5f694a9752fdb3639fed40e0dcca07a4ac7bf71c2e489f26d310eb9d3dd2eb6108460078234f5d5913d91315
+  data.tar.gz: f218d92e2b9631a12581778d71def4fbc6a27ed6581519fb8ff60ef3a436746b1c384cbacb9c6bd3fa2d75d9c4086d2d01036c97b69590783a44e6179407ba73

data/README.md

@@ -0,0 +1,154 @@
+# St. Baldrick's Ruby SDK
+
+### Installation
+`gem install stbaldricks`
+
+### Configuration
+* The sdk is configured using environment variables.
+* Required configurations:
+```
+API_ENDPOINT="https://stbaldricks.org/api"
+API_KEY="abc123"
+```
+
+### Usage
+* Require the gem
+`require 'stbaldricks'`
+
+* Configure the log level (optional)
+`SBF::Client::Configuration.logger.level = ::Logger::WARN`
+
+* **NOTE** the sdk does not raise execptions for failed requests. This is to allow for more complex logic around error scenarios.
+    * If you would like the client to raise errors by default you can wrap your requests in a helper
+``` ruby
+def request_helper
+  # Yield to the block to execute the request
+  client_response = yield
+
+  # If there was an error, raise it to the error handling block
+  if client_response.error?
+    puts "Error received from API. (code: #{client_response.http_code})"
+    puts JSON.pretty_generate(client_response.to_hash)
+
+    raise "Error received from API"
+  end
+
+  # Otherwise simply return the client data
+  client_response.data
+end
+```
+
+#### Default Entity Actions
+##### Lookup
+* Use `aggregate` to perform actions like gathering the size of a data set without returning all of the rows
+``` ruby
+active_donation_count = request_helper {
+  SBF::Client::Donation.aggregate([status: :active], {id: :count})
+}
+puts "Beginning number of active donations: #{active_donation_count[:id]}"
+```
+
+* Use `get` to get an entity by it's id fields
+``` ruby
+existing_donation = request_helper { SBF::Client::Donation.get(188) }
+puts "Donation: #{JSON.pretty_generate(existing_donation.to_hash)}"
+```
+
+#### Creation
+* To create an entity, create the object using `new` and persist the object to the database using `save`
+``` ruby
+# Find a random, active user to use as the recipient
+existing_participant = request_helper { SBF::Client::Participant.find({status: SBF::Client::Participant::Status::ACTIVE}) }[:results].sample
+recipient = SBF::Client::Donation::PartialParticipant.new(id: existing_participant.id)
+
+# Create a new donor profile. This will be saved at the same time as the donation
+# TODO: Create HowCreated of mobile?
+donor = SBF::Client::Donation::FullPerson.new(
+  status: SBF::Client::Person::Status::ACTIVE,
+  gender: SBF::Client::Person::Gender::NOT_SELECTED,
+  how_created: SBF::Client::Person::HowCreated::FAST_DONATION,
+  name_pieces: SBF::Client::NamePieces.new(
+    first_name: 'Foo',
+    last_name: 'Testerman'
+  ),
+  email_addresses: {
+    primary: SBF::Client::EmailAddress.new(
+      type: SBF::Client::EmailAddress::Type::PERSONAL,
+      email_address: 'foo.testerman@abcd.ef'
+    )
+  },
+  opt_out_settings: {
+    email_mass_online: true
+  }
+)
+
+# Payment details may be provided if the charging is completed.
+# Otherwise a nonce should be used which will be settled when the donation is saved
+payment_details = SBF::Client::Payment::CreditCardDetails.new(
+  authorization_id: 'abc123',
+  cardholder_name: 'Foo Testerman',
+  card_type: 'Visa',
+  expiration_date: '02/2027',
+  card_number: '************1234'
+)
+
+# Create the donation object itself. Status should be active unless this is a `submit cash` type donation.
+donation = SBF::Client::FullDonation.new(
+  status: SBF::Client::Donation::Status::ACTIVE,
+  amount: 50.00,
+  display_name: 'Test Display Name',
+  is_unrecognized: false,
+  how_created: SBF::Client::Donation::HowCreated::MOBILE,
+  donor: donor,
+  recipient: recipient,
+  payment_details: payment_details
+)
+
+request_helper { donation.save }
+puts "Added donation #{donation.id}"
+```
+
+#### Search Actions
+##### Text search
+``` ruby
+# Find all participants or fundraisers with 'John' in the searchable fields
+model_types = [SBF::Client::Search::Type::PARTICIPANT, SBF::Client::Search::Type::FUNDRAISER]
+participants_and_fundraisers = request_helper { SBF::Client::Search.find(model_types, 'John')}[:results]
+puts JSON.pretty_generate(participants_and_fundraisers)
+```
+
+##### Filtered Search
+``` ruby
+# Find all active events, teams, and fundraisers at the railyard event
+railyard_event = request_helper { SBF::Client::Event.find(venue: {location: {name: {like: "%Rail%"}}}, year: 2017) }[:results].first
+
+model_types = [SBF::Client::Search::Type::EVENT, SBF::Client::Search::Type::TEAM, SBF::Client::Search::Type::FUNDRAISER]
+filter = {
+  and: [
+    {column: 'status_id', operator: 'equals', value: SBF::Client::Search::Status::ACTIVE},
+    {column: 'event_id', operator: 'equals', value: railyard_event.id},
+    {column: 'event_year', operator: 'equals', value: railyard_event.year}
+  ]
+}
+
+entities_at_the_railyard = request_helper { SBF::Client::Search.find(model_types, nil, filter, nil, limit: 20) }[:results]
+puts JSON.pretty_generate(entities_at_the_railyard)
+```
+
+##### Geocode Search
+``` ruby
+# Find all active participants with 10 miles of Lincoln, NE
+require 'geocoder'
+data = Geocoder::Lookup.get(:google).search("Lincoln, NE").first
+lat = data.latitude.round(6)
+lon = data.longitude.round(6)
+geo_location = {lat: lat, lon: lon, distance: 200}
+
+model_type = SBF::Client::Search::Type::PARTICIPANT
+
+filter = {and: [{column: 'status_id', operator: 'equals', value: SBF::Client::Search::Status::ACTIVE}]}
+
+active_participant_within_10_mi = request_helper { SBF::Client::Search.find(model_type, nil, filter, geo_location, limit: 2) }[:results]
+puts JSON.pretty_generate(active_participant_within_10_mi)
+```
+

data/lib/stbaldricks/entities/donation.rb

@@ -147,6 +147,32 @@ module SBF
         end
       end
 
+      class FullPerson < SBF::Client::FullPerson
+        attr_reader :type
+
+        def type
+          SBF::Client::Donation::DonorType::INDIVIDUAL
+        end
+      end
+
+      class PartialPerson < SBF::Client::PartialPerson
+        attr_reader :type
+
+        def type
+          SBF::Client::Donation::DonorType::INDIVIDUAL
+        end
+      end
+
+      class FullOrganization < SBF::Client::FullPerson
+        attr_reader :type
+        private :type
+      end
+
+      class PartialOrganization < SBF::Client::PartialPerson
+        attr_reader :type
+        private :type
+      end
+
       class RecognitionCard < SBF::Client::BaseEntity
         class Recipient < SBF::Client::BaseEntity
           attr_reader :name
@@ -302,18 +328,18 @@ module SBF
         [
           [
             ->(v) { v[:type] == SBF::Client::Donation::DonorType::INDIVIDUAL },
-            'SBF::Client::FullPerson',
-            'SBF::Client::PartialPerson'
+            'SBF::Client::Donation::FullPerson',
+            'SBF::Client::Donation::PartialPerson'
           ],
           [
             ->(v) { v[:type] == SBF::Client::Donation::DonorType::BUSINESS },
-            'SBF::Client::FullOrganization',
-            'SBF::Client::PartialOrganization'
+            'SBF::Client::Donation::FullOrganization',
+            'SBF::Client::Donation::PartialOrganization'
           ],
           [
             ->(v) { v[:type] == SBF::Client::Donation::DonorType::ORGANIZATION_FOUNDATION },
-            'SBF::Client::FullOrganization',
-            'SBF::Client::PartialOrganization'
+            'SBF::Client::Donation::FullOrganization',
+            'SBF::Client::Donation::PartialOrganization'
           ]
         ],
         optional: true

data/lib/stbaldricks/version.rb

@@ -1,5 +1,5 @@
 module SBF
   module Client
-    VERSION = '4.3.2.alpha.2'
+    VERSION = '4.3.2.alpha.3'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stbaldricks
 version: !ruby/object:Gem::Version
-  version: 4.3.2.alpha.2
+  version: 4.3.2.alpha.3
 platform: ruby
 authors:
 - Firespring
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-11-14 00:00:00.000000000 Z
+date: 2017-11-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -74,6 +74,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
+- README.md
 - lib/stbaldricks.rb
 - lib/stbaldricks/api.rb
 - lib/stbaldricks/client.rb
@@ -215,7 +216,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.12
+rubygems_version: 2.7.0
 signing_key: 
 specification_version: 4
 summary: St. Baldrick's Foundation Ruby Client Library