virtuous 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c435c6a389b27d1644f8fa32d0df952aa9bcb83baf152973c8e2f55b0b418a1
+  data.tar.gz: 13075eb9634a01b1597c6a8be58444b1ec89738efe8842b124e4e640237163a4
+SHA512:
+  metadata.gz: 720aaf08ccabd9f7d1b7da3b07b4d028646c910c32605d85c4fe915050799eec9880b70f377674af848af13cab25fe18e92c3c6f460393499739188d5010ed29
+  data.tar.gz: 8b65f36c8bef728c092210f0448769b2d581d445755ca35d23eea6d1ae9e624bc9bad1602fa5edc4f0f45ac9920cf5f6c02b5877f07444366133422f9457d4bf

data/.github/workflows/test.yml

@@ -0,0 +1,26 @@
+name: Run specs
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - name: Install dependencies
+        run: bundle install
+      - name: Lint
+        run: |
+          bundle exec rubocop
+          bundle exec reek
+      - name: Run tests
+        run: bundle exec rspec

data/.gitignore

@@ -0,0 +1,5 @@
+virtuous-*.gem
+.env
+Gemfile.lock
+doc
+.yardoc

data/.reek.yml

@@ -0,0 +1,36 @@
+detectors:
+  IrresponsibleModule:
+    enabled: false
+  DataClump:
+    enabled: false
+  FeatureEnvy:
+    exclude:
+      - "Virtuous::Client#connection"
+      - "Virtuous::Client#unauthorized_connection"
+      - "Virtuous::HashHelper#self.deep_transform_keys"
+      - "FaradayMiddleware::ParseOj#on_complete"
+  NilCheck:
+    exclude:
+      - "Virtuous::Client#initialize"
+  UtilityFunction:
+    public_methods_only: true
+  NestedIterators:
+    exclude:
+      - "Virtuous::HashHelper#self.deep_transform_keys"
+  TooManyStatements:
+    exclude:
+      - "Virtuous::HashHelper#self.deep_transform_keys"
+      - "Virtuous::Client#connection"
+      - "Virtuous::Client#unauthorized_connection"
+      - "FaradayMiddleware::VirtuousErrorHandler#on_complete"
+  ControlParameter:
+    exclude:
+      - "Virtuous::Client#initialize"
+  NilCheck:
+    enabled: false
+  TooManyInstanceVariables:
+    exclude:
+      - "Virtuous::Client"
+  InstanceVariableAssumption:
+    exclude:
+      - "Virtuous::Client"

data/.rubocop.yml

@@ -0,0 +1,87 @@
+# All cops
+
+AllCops:
+  TargetRubyVersion: 2.7
+  NewCops: "enable"
+  Exclude:
+    - "bin/*"
+    - "vendor/**/*"
+
+# Layout cops
+
+Layout/LineLength:
+  Max: 100
+  # To make it possible to copy or click on URIs in the code, we allow lines
+  # containing a URI to be longer than Max.
+  AllowURI: true
+  URISchemes:
+    - http
+    - https
+
+# Metrics cops
+
+Metrics/AbcSize:
+  # The ABC size is a calculated magnitude, so this number can be an Integer or
+  # a Float.
+  Max: 15
+  Exclude:
+    - lib/virtuous/error.rb
+
+Metrics/BlockLength:
+  CountComments: false # count full line comments?
+  Max: 25
+  Exclude:
+    - config/**/*
+    - spec/**/*
+
+Metrics/BlockNesting:
+  Max: 4
+
+Metrics/ClassLength:
+  CountComments: false # count full line comments?
+  Max: 200
+
+# Avoid complex methods.
+Metrics/CyclomaticComplexity:
+  Max: 6
+  Exclude:
+    - lib/virtuous/error.rb
+
+Metrics/MethodLength:
+  CountComments: false # count full line comments?
+  Max: 24
+
+Metrics/ModuleLength:
+  CountComments: false # count full line comments?
+  Max: 200
+
+Metrics/ParameterLists:
+  Max: 5
+  CountKeywordArgs: true
+
+Metrics/PerceivedComplexity:
+  Max: 12
+
+# Style cops
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/ModuleFunction:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: false
+
+# Lint cops
+
+Lint/AmbiguousBlockAssociation:
+  Exclude:
+    - spec/**/*
+
+Naming/MemoizedInstanceVariableName:
+  Exclude:
+    - lib/virtuous/client.rb

data/.ruby-version

@@ -0,0 +1 @@
+3.2.2

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- A Client class with support for api key and OAuth authentication
+- Methods to find, create and update contacts
+- Methods to find, create, update and delete individuals
+- Methods to find, create, update and delete gifts
+- Method query gift designations
+
+[unreleased]: https://github.com/taylorbrooks/virtuous/compare/v0.0.0...HEAD

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'bundler', '~> 2.3'
+gem 'dotenv', '~> 2.8.1'
+gem 'pry', '~> 0.14.2'
+gem 'puma', '~> 6.4'
+gem 'rake', '~> 12.3.3'
+gem 'reek', '~> 6.1'
+gem 'rspec', '~> 3.7'
+gem 'rubocop', '~> 1.57'
+gem 'sinatra', '~> 2.0'
+gem 'webmock', '~> 3.1'
+gem 'yard', '~> 0.9'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Taylor Brooks
+
+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,54 @@
+<img src="./logo/virtuous.svg" width="200" />
+
+# Virtuous Ruby Client ![example workflow](https://github.com/taylorbrooks/virtuous/actions/workflows/test.yml/badge.svg)
+
+A Ruby wrapper for the Virtuous API
+
+To get a general overview of Virtuous: https://virtuous.org
+
+[RDocs](https://rubydoc.info/github/taylorbrooks/virtuous/master)
+
+### Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+  # in your Gemfile
+  gem 'virtuous', '~> 0.0.1'
+
+  # then...
+  bundle install
+```
+
+### Usage
+
+```ruby
+  # Authenticating with username and password
+  client = Virtuous::Client.new
+  client.authenticate(username: ..., password: ...)
+
+  # Authenticating with api keys
+  client = Virtuous::Client.new(api_key: ...)
+
+  # Find a specific contact
+  client.find_contact_by_email('gob@bluthco.com')
+```
+
+### History
+
+View the [changelog](https://github.com/taylorbrooks/virtuous/blob/master/CHANGELOG.md)
+
+This gem follows [Semantic Versioning](http://semver.org/)
+
+### Contributing
+
+Everyone is encouraged to help improve this project. Here are a few ways you can help:
+
+- [Report bugs](https://github.com/taylorbrooks/virtuous/issues)
+- Fix bugs and [submit pull requests](https://github.com/taylorbrooks/virtuous/pulls)
+- Write, clarify, or fix documentation
+- Suggest or add new features
+
+### Copyright
+
+Copyright (c) 2018 Taylor Brooks. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,24 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+task :environment do
+  require 'dotenv'
+  Dotenv.load
+
+  $LOAD_PATH.unshift File.expand_path('lib', __dir__)
+  require 'virtuous'
+end
+
+desc 'Launch a pry shell with libraries loaded'
+task pry: :environment do
+  options = {}
+  options[:logger] = Logger.new($stdout) unless ENV['CLIENT_LOGGER'].nil?
+  @client = Virtuous::Client.new(**options) if ENV['VIRTUOUS_KEY']
+
+  require 'pry'
+  Pry.start
+end

data/lib/virtuous/client/contact.rb

@@ -0,0 +1,220 @@
+module Virtuous
+  class Client
+    ##
+    # ### Contact data
+    #
+    #     {
+    #       contact_type: [String],
+    #       reference_source: [String],
+    #       reference_id: [String],
+    #       name: [String],
+    #       informal_name: [String],
+    #       description: [String],
+    #       website: [String],
+    #       marital_status: [String],
+    #       anniversary_month: [Integer],
+    #       anniversary_day: [Integer],
+    #       anniversary_year: [Integer],
+    #       origin_segment_id: [Integer],
+    #       is_private: [Boolean],
+    #       is_archived: [Boolean],
+    #       contact_addresses: [
+    #         {
+    #           label: [String],
+    #           address1: [String],
+    #           address2: [String],
+    #           city: [String],
+    #           state_code: [String],
+    #           postal: [String],
+    #           country_code: [String],
+    #           is_primary: [Boolean],
+    #           latitude: [Float],
+    #           longitude: [Float]
+    #         }
+    #       ],
+    #       contact_individuals: [
+    #         {
+    #           first_name: [String],
+    #           last_name: [String],
+    #           prefix: [String],
+    #           middle_name: [String],
+    #           suffix: [String],
+    #           birth_month: [Integer],
+    #           birth_day: [Integer],
+    #           birth_year: [Integer],
+    #           approximate_age: [Integer],
+    #           gender: [String],
+    #           passion: [String],
+    #           is_primary: [Boolean],
+    #           is_secondary: [Boolean],
+    #           is_deceased: [Boolean],
+    #           contact_methods: [
+    #             {
+    #               type: [String],
+    #               value: [String],
+    #               is_opted_in: [Boolean],
+    #               is_primary: [Boolean]
+    #             }
+    #           ],
+    #           custom_fields: [Hash]
+    #         }
+    #       ],
+    #       custom_fields: [Hash],
+    #       custom_collections: [
+    #         {
+    #           name: [String],
+    #           fields: [
+    #             {
+    #               name: [String],
+    #               value: [String]
+    #             }
+    #           ]
+    #         }
+    #       ]
+    #     }
+    #
+    module Contact
+      ##
+      # Fetches a contact record by email.
+      #
+      # @example
+      #     client.find_contact_by_email('contact@email.com')
+      #
+      # @param email [String] The email of the contact.
+      #
+      # @return [Hash] The contact information in a hash.
+      def find_contact_by_email(email)
+        parse(get('api/Contact/Find', { email: email }))
+      end
+
+      ##
+      # Fetches a contact record by id.
+      #
+      # @example
+      #     client.get_contact(1)
+      #
+      # @param id [Integer] The id of the contact.
+      #
+      # @return [Hash] The contact information in a hash.
+      def get_contact(id)
+        parse(get("api/Contact/#{id}"))
+      end
+
+      ##
+      # Creates a contact. This will use the virtuous import tool to match the new contact
+      # with existing ones. If the contact record exists already but there is new
+      # information the record will be flagged for review.
+      #
+      # Transactions are posted to the API and are set to a holding state.
+      # At midnight, transactions are bundled into imports based on the source they were posted
+      # with.
+      # The organization reviews the imported transactions, and then clicks run.
+      #
+      # @example
+      #     client.import_contact(
+      #       contact_type: 'Organization', name: 'Org name',
+      #       first_name: 'John', last_name: 'Doe'
+      #     )
+      #
+      # @param data [Hash] A hash containing the contact details.
+      #
+      # #### Required fields
+      # - `contact_type`: "Household", "Organization", "Foundation" or a custom type.
+      # - `contact_name`: required if Organization or Foundation.
+      # - `first_name`
+      # - `last_name`
+      #
+      # #### Suggested fields
+      # - `reference_source`: the system it came from.
+      # - `reference_id`: the ID in the original system.
+      # - `email`
+      # - `phone`
+      # - `address`
+      #
+      # #### Full list of accepted fields
+      #
+      #     {
+      #       reference_source: [String],
+      #       reference_id: [String],
+      #       contact_type: [String],
+      #       name: [String],
+      #       title: [String],
+      #       first_name: [String],
+      #       middle_name: [String],
+      #       last_name: [String],
+      #       suffix: [String],
+      #       email_type: [String],
+      #       email: [String],
+      #       phone_type: [String],
+      #       phone: [String],
+      #       address1: [String],
+      #       address2: [String],
+      #       city: [String],
+      #       state: [String],
+      #       postal: [String],
+      #       country: [String],
+      #       event_id: [Integer],
+      #       event_name: [String],
+      #       invited: [Boolean],
+      #       rsvp: [Boolean],
+      #       rsvp_response: [Boolean],
+      #       attended: [Boolean],
+      #       tags: [String],
+      #       origin_segment_code: [String],
+      #       email_lists: [String[]],
+      #       custom_fields: [Hash],
+      #       volunteer_attendances: [
+      #         {
+      #           volunteer_opportunity_id: [Integer],
+      #           volunteer_opportunity_name: [String],
+      #           date: [String],
+      #           hours: [String]
+      #         }
+      #       ]
+      #     }
+      #
+      def import_contact(data)
+        post('api/Contact/Transaction', format(data))
+      end
+
+      ##
+      # Creates a contact.
+      #
+      # @example
+      #     client.create_contact(
+      #       contact_type: 'Organization', name: 'Org name',
+      #       contact_individuals: [
+      #         { first_name: 'John', last_name: 'Doe' }
+      #       ]
+      #     )
+      #
+      # @param data [Hash] A hash containing the contact details.
+      #   Refer to the [Contact data](#label-Contact+data) section
+      #   above to see the available attributes.
+      #
+      # @return [Hash] The contact that has been created.
+      def create_contact(data)
+        parse(post('api/Contact', format(data)))
+      end
+
+      ##
+      # Updates a contact.
+      #
+      # @example
+      #     client.update_contact(1, contact_type: 'Organization', name: 'New name')
+      #
+      # @note Excluding a property will remove it's value from the object.
+      # If you're only updating a single property, the entire model is still required.
+      #
+      # @param id [Integer] The id of the contact to update.
+      # @param data [Hash] A hash containing the contact details.
+      #   Refer to the [Contact data](#label-Contact+data) section
+      #   above to see the available attributes.
+      #
+      # @return [Hash] The contact that has been updated.
+      def update_contact(id, data)
+        parse(put("api/Contact/#{id}", format(data)))
+      end
+    end
+  end
+end

data/lib/virtuous/client/contact_address.rb

@@ -0,0 +1,78 @@
+module Virtuous
+  class Client
+    ##
+    # ### Contact Address data
+    #
+    #     {
+    #       contact_id: [Integer],
+    #       label: [String],
+    #       address1: [String],
+    #       address2: [String],
+    #       city: [String],
+    #       state: [String],
+    #       postal: [String],
+    #       country: [String],
+    #       set_as_primary: [Boolean],
+    #       start_month: [Integer],
+    #       start_day: [Integer],
+    #       end_month: [Integer],
+    #       end_day: [Integer]
+    #     }
+    #
+    module ContactAddress
+      ##
+      # Gets the addresses of a contact.
+      #
+      # @example
+      #     client.get_contact_addresses(1)
+      #
+      # @param contact_id [Integer] The id of the Contact.
+      #
+      # @return [Array] An array with all the addresses of a contact.
+      #
+      def get_contact_addresses(contact_id)
+        response = get("api/ContactAddress/ByContact/#{contact_id}")
+        response.map { |address| parse(address) }
+      end
+
+      ##
+      # Updates an address.
+      #
+      # @example
+      #     client.update_contact_address(
+      #       1, label: 'Home address', address1: '324 Frank Island', address2: 'Apt. 366',
+      #       city: 'Antonioborough', state: 'Massachusetts', postal: '27516', country: 'USA'
+      #     )
+      #
+      # @note Excluding a property will remove it's value from the object.
+      # If you're only updating a single property, the entire model is still required.
+      #
+      # @param id [Integer] The id of the address to update.
+      # @param data [Hash] A hash containing the address details.
+      #   Refer to the data section above to see the available attributes.
+      #
+      # @return [Hash] The address that has been updated.
+      def update_contact_address(id, data)
+        parse(put("api/ContactAddress/#{id}", format(data)))
+      end
+
+      ##
+      # Creates an address.
+      #
+      # @example
+      #     client.create_contact_address(
+      #       contact_id: 1, label: 'Home address', address1: '324 Frank Island',
+      #       address2: 'Apt. 366', city: 'Antonioborough', state: 'Massachusetts', postal: '27516',
+      #       country: 'USA'
+      #     )
+      #
+      # @param data [Hash] A hash containing the address details.
+      #   Refer to the data section above to see the available attributes.
+      #
+      # @return [Hash] The address that has been created.
+      def create_contact_address(data)
+        parse(post('api/ContactAddress', format(data)))
+      end
+    end
+  end
+end