coach_client 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b81cdba0479cf3487db59bcba3349987013d19d4
+  data.tar.gz: b558de83c4e17635e30bdb3ffc7b7111a091efb6
+SHA512:
+  metadata.gz: 86b8e17b0278409dff0184226199bfd352b05d549bcd70b465ba69f82ae2b0cf31d7f1a4fb9b331870582360186b5f0cbfdbd2d7510b6798f7c7539cd4a02b44
+  data.tar.gz: 7848b199030c69a7f95cbd39fb01395a18a065cc07412b78d9a6ee75f91567e42eb033bba9f4d2c003c6a1f6db7cea7da37c4a5a2cc169653973d0efb202d234

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,4 @@
+language: ruby
+rvm:
+  - 2.2.3
+before_install: gem install bundler -v 1.10.6

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Michael Jungo
+
+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,248 @@
+# CoachClient
+[![Gem Version](https://badge.fury.io/rb/coach_client.svg)](https://badge.fury.io/rb/coach_client)
+
+A wrapper around the
+[CyberCoach](https://diuf.unifr.ch/drupal/softeng/teaching/studentprojects/cyber-coach-rest)
+API of the University of Fribourg.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'coach_client'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install coach_client
+
+## Documentation
+
+- [Rubygem website](https://rubygems.org/gems/coach_client)
+- [Documentation](http://www.rubydoc.info/gems/coach_client/0.1.0)
+- [GitHub](https://github.com/jungomi/coach_client)
+
+## Usage
+
+### Client
+
+Every action to a CyberCoach service requires a client. The client contains the
+URL to the service and provides some methods to retrieve resources.
+
+```ruby
+client = CoachClient::Client.new('http://diufvm31.unifr.ch:8090',
+                                 '/CyberCoachServer/resources/')
+```
+
+### Resources
+
+All CyberCoach resources follow the same basic principles.
+- `save` saves the resource on the CyberCoach service (creates or overwrites it).
+- `update` updates the resource with the data from CyberCoach service (fetch).
+- `delete` deletes the resource on the CyberCoach service.
+- `exist?` returns whether the resource exists on the CyberCoach service.
+
+#### User
+
+A user is identified by the username which has to be specified on creation.
+
+```ruby
+user = CoachClient::User.new(client, 'myusername')
+```
+
+All the attributes of the user can be accessed and changed directly
+
+```ruby
+user.username                #=> "myusername"
+user.password                #=> nil
+user.password = 'mypassword' #=> "mypassword"
+```
+
+Or the attributes can be supplied as optional arguments on creation
+
+```ruby
+user = CoachClient::User.new(client, 'myusername', password: 'mypassword')
+user.username #=> "myusername"
+user.password #=> "mypassword"
+```
+
+A list of users can be obtained with the class method `list`. It takes an
+optional block, which acts as a filter and therefore only returns the users for
+which the block returns a true value. If the block is omitted, the whole list is
+returned.  
+The list is divided into chunks by the CyberCoach service. To retrieve the
+complete list the optional parameter `all` can be set to true.  
+As the user informations are not provided in the list, each user has to be
+updated individually in order to apply filtering on them. **This requires a GET
+request every time**.
+
+```ruby
+# lists only the users with a username with less than 5 characters
+CoachClient::User.list(client) { |user| user.username.length < 5 }
+
+# lists all available users
+CoachClient::User.list(client, all: true)
+
+# lists only the users with an email address ending with '.ch'
+CoachClient::User.list(client) do |user|
+  user.update # required to retrieve email address
+  user.email.end_with?('.ch')
+end
+```
+
+To verify if the credentials are valid the method `authenticated?` is used.
+If credentials need to be tested without having to create a new user, the
+method in the client can be used.
+
+```ruby
+user.authenticated? #=> true
+
+client.authenticated?('myusername', 'mypassword') #=> true
+```
+
+#### Partnership
+
+A partnership is a relationship between two users. The users can be passed as
+`CoachClient::User` objects. If this it not the case, it tries to create them.  
+Passing a user object is recommended because it contains the already established
+informations (most importantly the password, which is needed for some requests).
+The users can be accessed and changed accordingly.
+
+```ruby
+# partnership between the user created above and a user with the username 'mypartner'
+partnership = CoachClient::Partnership.new(client, user, 'mypartner')
+
+# set password of 'mypartner'
+partnership.user2.password = 'hispassword'
+```
+
+The partnership provides a class method `list` is used to obtain a list of
+partnerships, which works the same way as the `User.list`.
+
+```ruby
+# lists only the partnerships for which user1 is 'myusername' and the 
+# user2 has confirmed the partnership.
+CoachClient::Partnership.list(client) do |partnership|
+  return false unless partnership.user1.username == 'myusername'
+  partnership.update # only update when the first condition succeeded
+  partnership.user2_confirmed
+end
+```
+
+To obtain the partnerships of a specific user, use the partnerships attribute of
+the user, instead of traversing the entire list. Even though the partnership
+on the CyberCoach service does not always provide the user that had done the
+request as the first user in the partnership, the list of partnerships returned
+ensures that `user1 == user`.
+
+```ruby
+user.update # needed to get the partnerships from the CyberCoach service
+user.partnerships
+
+user.partnerships.all? { |partnership| partnership.user1 == user } #=> true
+```
+
+The partnership uses the following methods to modify its status:
+- `propose` proposes a partnership by user1
+- `confirm` confirms a partnership by user2
+- `invalidate` invalidates the confirmations of user2
+
+When using `save` on a partnership that is not operational, it first tries to
+propose and confirm it. Similarly `delete` will try to invalidate it before
+deleting it.
+
+#### Sport
+
+The sport resource cannot be modified on the CyberCoach service and therefore
+the methods `save` and `delete` are not supported.  
+The sports are identified by a `Symbol` of their names. On creation the name is
+converted into a symbol. The name is case insensitive.
+
+```ruby
+sport  = CoachClient::Sport.new(client, :running)
+sport2 = CoachClient::Sport.new(client, 'running')
+sport3 = CoachClient::Sport.new(client, 'RUnNinG')
+
+sport.sport  #=> :running
+sport2.sport #=> :running
+sport3.sport #=> :running
+```
+
+The list of sports can be obtained with the class method `list` in the same
+manner as the users and partnerships.
+
+#### Subscription
+
+A subscription consists of sport and either a user or a partnership. For that
+matter use `CoachClient::UserSubscription` and
+`CoachClient::PartnershipSubscription` respectively. They are essentially the
+same besides the subject being a user or a partnership and can therefore be
+used almost identically.
+
+As for the other resources the user or partnership and the sport may be passed
+as the corresponding object. When an argument is not the object, it tries to
+create it. For partnerships a string representation is expected in that case,
+which represents the two users involved separated by a semicolon.
+Using already existing objects is recommended to preserve the already assigned
+attributes.
+
+```ruby
+user_sub = CoachClient::UserSubscription.new(client, user, sport)
+part_sub = CoachClient::PartnershipSubscription.new(client, partnership, sport)
+```
+
+To retrieve the subscriptions of a particular user or partnership, the
+subscriptions attribute of the respective object is used.
+
+```ruby
+user.update # needed to get the subscriptions from the CyberCoach service
+user.subscriptions
+
+partnership.update # needed to get the subscriptions from the CyberCoach service
+partnership.subscriptions
+```
+
+#### Entry
+
+An entry corresponds to subscription. The entry provides the method `create` to
+create a new entry. This is automatically invoked when trying to save it, if the
+entry does not exist on the CyberCoach service. When create is used on an
+already existing entry, it creates a new one with the same attributes (apart
+from the id).
+
+```ruby
+entry = CoachClient::Entry.new(client, user_sub, publicvisible: 2, comment: 'my comment')
+
+entry.exist?  #=> false
+entry.save
+entry.id      #=> 1
+entry.comment #=> 'my comment'
+entry.exist?  #=> true
+
+entry.create
+entry.id      #=> 2
+entry.comment #=> 'my comment'
+```
+
+To see all entries of a subscription use the attribute entries of the
+subscription.
+
+```ruby
+user_sub.update # needed to get the entries from the CyberCoach service
+user.entries
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/jungomi/coach_client).
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

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 "coach_client"
+
+# 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,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/coach_client.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'coach_client/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "coach_client"
+  spec.version       = CoachClient::VERSION
+  spec.authors       = ["Michael Jungo", "Amanda Karavolia", "Andrea Liechti", "Jocelyn Thode", "Simon Brulhart"]
+  spec.email         = ["michael.jungo@unifr.ch"]
+
+  spec.summary       = %q{A wrapper around the CyberCoach API of unifr}
+  spec.homepage      = "https://github.com/jungomi/coach_client"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "bin"
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 2.1.0"
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.4.0"
+  spec.add_development_dependency "webmock", "~> 1.22.3"
+  spec.add_development_dependency "vcr", "~> 2.9.3"
+
+  spec.add_dependency "gyoku", "~> 1.3.1"
+  spec.add_dependency "rest-client", "~> 1.8"
+end

data/lib/coach_client/client.rb

@@ -0,0 +1,84 @@
+module CoachClient
+  # A client to communicate with the CyberCoach service.
+  class Client
+    # The URL of the CyberCoach service.
+    #
+    # @return [String]
+    attr_reader :url
+
+    # Creates a new client with the CyberCoach informations.
+    #
+    # @param [String] host the host address
+    # @param [String] path the path to the resources
+    # @return [CoachClient::Client]
+    def initialize(host, path = '/')
+      @url = host + path
+    end
+
+    # Returns whether the given credentials are valid.
+    #
+    # @param [String] username
+    # @param [String] password
+    # @return [Boolean]
+    def authenticated?(username, password)
+      begin
+        CoachClient::Request.get("#{@url}authenticateduser/",
+                                 username: username, password: password)
+        true
+      rescue CoachClient::Unauthorized
+        false
+      end
+    end
+
+    # Returns the sport from the CyberCoach service.
+    #
+    # @param [String, Symbol] sportname
+    # @return [CoachClient::Sport]
+    def get_sport(sportname)
+      sport = CoachClient::Sport.new(self, sportname)
+      sport.update
+    end
+
+    # Returns the user from the CyberCoach service.
+    #
+    # @param [String] username
+    # @return [CoachClient::User]
+    def get_user(username)
+      user = CoachClient::User.new(self, username)
+      user.update
+    end
+
+    # Returns the partnership from the CyberCoach service.
+    #
+    # @param [CoachClient::User, String] user1
+    # @param [CoachClient::User, String] user2
+    # @return [CoachClient::Partnership]
+    def get_partnership(user1, user2)
+      partnership = CoachClient::Partnership.new(self, user1, user2)
+      partnership.update
+    end
+
+    # Returns the subscription of a user from the CyberCoach service.
+    #
+    # @param [CoachClient::User, String] user
+    # @param [CoachClient::Sport, String, Symbol] sport
+    # @return [CoachClient::UserSubscription]
+    def get_user_subscription(user, sport)
+      subscription = CoachClient::UserSubscription.new(self, user, sport)
+      subscription.update
+    end
+
+    # Returns the subscription of a partnership from the CyberCoach service.
+    #
+    # @param [CoachClient::User, String] user1
+    # @param [CoachClient::User, String] user2
+    # @param [CoachClient::Sport, String, Symbol] sport
+    # @return [CoachClient::PartnershipSubscription]
+    def get_partnership_subscription(user1, user2, sport)
+      partnership = CoachClient::Partnership.new(self, user1, user2)
+      subscription = CoachClient::PartnershipSubscription.new(self, partnership, sport)
+      subscription.update
+    end
+  end
+end
+