d2l-valence 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 54c02bc20fd56e2ae54c623a642d0b6f8f83d493
+  data.tar.gz: d55700ebfc5b739baf6dcf79e08059450f5d2946
+SHA512:
+  metadata.gz: f99a543b75d5da9219d4a27ce3a45b6c3fdad283ddb86e84f942e6cd366731b16bd80dce18b2e739b150f6df26622b14fd76a44861da404ae19774df2bbda8a9
+  data.tar.gz: 4d7a8d8d88a0b406af1967252b13fca056afb3b1173b342742f7bd62652885be6e1f086be1ad38e46c613148c75934d6d7d6efffebdc025e8887bef0ee7c2253

data/.codeclimate.yml

@@ -0,0 +1,22 @@
+---
+engines:
+  bundler-audit:
+    enabled: true
+  duplication:
+    enabled: true
+    config:
+      languages:
+      - ruby
+  fixme:
+    enabled: true
+  rubocop:
+    enabled: true
+ratings:
+  paths:
+  - Gemfile.lock
+  - "lib/**/*"
+exclude_paths:
+  - spec/
+  - .idea/
+  - sandpit/
+

data/.gitignore

@@ -0,0 +1,17 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+/.idea
+.ruby-version
+.ruby-gemset
+/sandpit

data/.rubocop.yml

@@ -0,0 +1,13 @@
+AllCops:
+  Include:
+    - rubocop-rspec
+  Exclude:
+    - 'spec/**/*'
+    - '.idea/**/*'
+    - 'sandpit/**/*'
+    - 'Rakefile'
+  TargetRubyVersion: 2.3
+Metrics/LineLength:
+  Max: 120
+Style/FrozenStringLiteralComment:
+  Enabled: false

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,71 @@
+PATH
+  remote: .
+  specs:
+    d2l-valence (0.0.1)
+      rest-client (~> 2.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.5.0)
+      public_suffix (~> 2.0, >= 2.0.2)
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
+    diff-lcs (1.3)
+    domain_name (0.5.20170223)
+      unf (>= 0.0.5, < 1.0.0)
+    hashdiff (0.3.2)
+    http-cookie (1.0.3)
+      domain_name (~> 0.5)
+    mime-types (3.1)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2016.0521)
+    netrc (0.11.0)
+    public_suffix (2.0.5)
+    rake (10.4.2)
+    rest-client (2.0.1)
+      http-cookie (>= 1.0.2, < 2.0)
+      mime-types (>= 1.16, < 4.0)
+      netrc (~> 0.8)
+    rspec (3.4.0)
+      rspec-core (~> 3.4.0)
+      rspec-expectations (~> 3.4.0)
+      rspec-mocks (~> 3.4.0)
+    rspec-core (3.4.4)
+      rspec-support (~> 3.4.0)
+    rspec-expectations (3.4.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-its (1.2.0)
+      rspec-core (>= 3.0.0)
+      rspec-expectations (>= 3.0.0)
+    rspec-mocks (3.4.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-support (3.4.1)
+    safe_yaml (1.0.4)
+    timecop (0.8.1)
+    unf (0.1.4)
+      unf_ext
+    unf_ext (0.0.7.2)
+    vcr (3.0.3)
+    webmock (2.0.3)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.7)
+  d2l-valence!
+  rake (~> 10.0)
+  rspec (~> 3.4.0)
+  rspec-its (~> 1.2.0)
+  timecop (~> 0.8.1)
+  vcr (~> 3.0.0)
+  webmock (~> 2.0.0)
+
+BUNDLED WITH
+   1.14.3

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2017 Michael Harrison
+
+MIT License
+
+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,266 @@
+# D2l::Valence
+
+This gem is aimed at providing  a Ruby client for Desire2Learn's Valence Learning Framework APIs primarily 
+used for integration with D2L Brightspace
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'd2l-valence'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install d2l-valence
+
+## Usage
+
+The first step is to get an API Key generated by your D2L Brightspace Admin.  They will require you to provide a  
+`Trusted URL`.  This is the URL in your application that processes the authorisation response from the D2L Brightspace 
+Server.  If you do not have a hosted server for you application at the time of development then you can use the AP Test 
+Tool provided by D2L as the `Trusted URL`: https://apitesttool.desire2learnvalence.com/index.php
+
+Once generated the key will include an `Application ID` and `Application Key` which is used in the authentication request.
+
+
+### Authentication URL
+To start the process of authentication you will need to generate an Authentication URL.
+
+```ruby
+app_context = D2L::Valence::AppContext.new(
+  brightspace_host: 'partners.brightspace.com',
+  app_id: 'l3LcL9Lvpyg-ViYNbK',
+  app_key: 'mz5HRx6ER6jLMqKRv6Fw',
+  api_version: '1.15' # optional defaults to 1.0
+)
+
+auth_url = app_context.auth_url('https://apitesttool.desire2learnvalence.com/index.php')
+```
+
+Once you have generated your authentication URL you can do a redirect to it in your application if you have your 
+application hosted.  If you application is not hosted as yet and you're using the D2L API Test Tool then just paste the
+URL into your browser and the API Test Tool will appear.  From there you'll be able to get the `User ID` and `User Key` 
+which will be used in all subsequent authenticated requests.
+
+__NB:__ You will need to be authenticated on your instance of D2L Brightspace in order for the above function as expected.
+The Valence API uses that account for all subsequent authenticated requests for authorisation so it's important that 
+you are authenticated with the right account.
+
+### Authenticated Requests  
+The D2L Valence API requires that all requests are signed with authentication details.  This is based on your `App ID` 
+and `App Key` along with the `User ID` and `User Key` that you harvest from the authentication response from your D2L 
+Server.  
+ 
+#### User context creation
+In order to make requests against the D2L Valence API you will need to create a `D2L::Valence::UserContext` instance.  This 
+will then be used for all of your subsequent requests against the various D2L Valence APIs.  Following is an example of 
+the user context creation when processing the D2L Authentication response.
+
+```ruby
+app_context = D2L::Valence::AppContext.new(
+  brightspace_host: 'partners.brightspace.com',
+  app_id: 'l3LcL9Lvpyg-ViYNbK',
+  app_key: 'mz5HRx6ER6jLMqKRv6Fw',
+  api_version: '1.15' # optional defaults to 1.0
+)
+  
+user_id = params['x_a'] # query parameters from the response
+user_key = params['x_b']
+  
+user_context = D2L::Valence::UserContext.new(
+  app_context: app_context,
+  user_id: user_id,
+  user_key: user_key
+)
+
+```
+
+Please note if you're using a application framework that supports sessions (e.g. Rails, Sinatra, etc) then it's probably 
+best store the `User ID` and `User Key` in the session to allow for multiple API requests.
+
+
+#### Route Format
+When creating your request you will need to specify a `rout`.  The format of the `route` provided when doing a request 
+allows you to specify parameters that are replaced based on the `route_params` hash that you provide in the request 
+creation.  The only parameter that's pre-populated is the `version` which is based on the api_version you supply when 
+creating your application context.  It can, however be overridden when you supply your `route_params`.  Following are 
+some examples of `route` and `route_params`
+
+```ruby
+
+# NB: For the following example the api_version in the app_context has been set to 1.0
+
+route = '/d2l/api/lp/:version/:orgUnitId/groupcategories/:groupCategoryId'
+route_params = {orgUnitId: 1, groupCategoryId: 23} # => /d2l/api/lp/1.0/1/groupcategories/23
+
+route = '/d2l/api/lp/:version/users/whoami'
+route_params = {version: '1.15'} # => /d2l/api/lp/1.15/users/whoami
+
+```
+
+### Request Examples
+
+#### GET Request example
+
+[GET /d2l/api/lp/(version)/users/whoami](http://docs.valence.desire2learn.com/res/user.html#get--d2l-api-lp-(version)-users-whoami)
+
+```ruby
+response = D2L::Valence::Request.new(
+  user_context: user_context,
+  http_method: 'GET',
+  route: '/d2l/api/lp/:version/users/whoami'
+).execute
+
+response.code # => :HTTP_200
+response.to_hash # => will yield the following hash
+{
+  "Identifier" => "1",
+  "FirstName" => "Jack",
+  "LastName" => "User",
+  "UniqueName" => "jack.user",
+  "ProfileIdentifier" => "OqW9594ZXT"
+}
+```
+
+#### POST Request example
+[POST /d2l/api/le/(version)/lti/link/(orgUnitId)¶](http://docs.valence.desire2learn.com/res/lti.html#post--d2l-api-le-(version)-lti-link-(orgUnitId))
+
+```ruby
+
+response = D2L::Valence::Request.new(
+  user_context: user_context,
+  http_method: 'POST',
+  route: '/d2l/api/le/:version/lti/link/:orgUnitId',
+  route_params: { orgUnitId: 123 },
+  query_params: {
+    Title: 'LTI Link',
+    Url: 'http://myapplication.com/tool/launch',
+    Description: 'Link for external tool',
+    Key: '2015141297208',
+    PlainSecret: 'a30be7c3550149b7a7daac3065f0e5e5',
+    IsVisible: false,
+    SignMessage: true,
+    SignWithTc: true,
+    SendTcInfo: true,
+    SendContextInfo: true,
+    SendUserId: true,
+    SendUserName: true,
+    SendUserEmail: true,
+    SendLinkTitle: true,
+    SendLinkDescription: true,
+    SendD2LUserName: true,
+    SendD2LOrgDefinedId: true,
+    SendD2LOrgRoleId: true,
+    UseToolProviderSecuritySettings: true,
+    CustomParameters: nil
+  }
+).execute
+
+response.code # => :HTTP_200
+response.to_hash # => full details of the created LTI Link with OrgUnitId and LtiLinkId included
+```
+
+#### PUT Request example
+[PUT /d2l/api/le/(version)/lti/link/(ltiLinkId)](http://docs.valence.desire2learn.com/res/lti.html#put--d2l-api-le-(version)-lti-link-(ltiLinkId))
+
+```ruby
+response = D2L::Valence::Request.new(
+  user_context: user_context,
+  http_method: 'PUT',
+  route: '/d2l/api/le/:version/lti/link/:ltiLinkId',
+  route_params: { ltiLinkId: '123' },
+  query_params: { Title: 'New LTI Link Title' }
+).execute
+
+response.code # => :HTTP_200
+response.to_hash # => full details of the updated LTI Link with OrgUnitId and LtiLinkId included
+```
+
+#### DELETE Request example
+[DELETE /d2l/api/le/(version)/lti/link/(ltiLinkId)](http://docs.valence.desire2learn.com/res/lti.html#delete--d2l-api-le-(version)-lti-link-(ltiLinkId))
+
+```ruby
+response = D2L::Valence::Request.new(
+  user_context: user_context,
+  http_method: 'DELETE',
+  route: '/d2l/api/le/:version/lti/link/:ltiLinkId',
+  route_params: { ltiLinkId: '123' }
+).execute
+
+response.code # => :HTTP_200
+response.to_hash # => {}
+
+```
+
+#### Request failures  
+Other than the normal HTTP response codes for failures there are a number of D2L Valence API specific response codes 
+that will appear with the right conditions.
+
+##### :INVALID_TIMESTAMP  
+This response code identifies that there is enough of a difference between your local server time and the D2L Server 
+time to be a problem.  For developers this is hard to have changed so we provided a mechanism where by the failure can 
+be rectified at the application level.  In the design of the gem there is detection of time skew between the client and
+server.  This is compensated for automatically.  Should your request get this failure then all you need do is execute 
+your request a second time and the gem will take the skew into consideration when creating the necessary authentication 
+tokens.  Following is an example of handling the response:
+
+```ruby
+request = D2L::Valence::Request.new(
+  user_context: user_context,
+  http_method: 'GET',
+  route: '/d2l/api/lp/:version/users/whoami'
+)
+
+response = request.execute
+response = request.execute if response.code == :INVALID_TIMESTAMP
+response.code # => :HTTP_200
+
+```
+
+##### :INVALID_TOKEN  
+This response code occurs, as it suggests when you have provided an invalid set of authentication tokens.  This could 
+be a combination of incorrect App ID/Key and/or User ID/Key.   
+ 
+## Contributing
+
+1. Fork it ( https://github.com/michael-harrison/d2l-valence/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+### Testing notes  
+Given the use of timestamps in the the URL it does mean that any tests that have recorded HTTP traffic via [VCR](https://github.com/vcr/vcr) 
+need to use [Timecop](https://github.com/travisjeffery/timecop).  In some cases the calls will need to wrapped with a 
+Timecop block:
+
+```ruby
+Timecop.freeze Time.at(1491780043) do
+  # Your HTTP Calls
+end
+```
+
+But for the majority of the tests it just a matter of adding a `before` and `after`:
+
+```ruby
+before { Timecop.freeze Time.at(1491547536) }
+after { Timecop.return }
+```
+
+In order to do PRs with passing tests you'll need to use your own temporary App ID, App Key, User ID and User Key as I've
+done with these tests.  For convenience the tests uses environment variables:
+ 
+```ruby
+let(:app_id) { ENV['D2L_API_ID'] }
+let(:app_key) { ENV['D2L_API_KEY'] }
+let(:user_id) { ENV['D2L_USER_ID'] }
+let(:user_key) { ENV['D2L_USER_KEY'] }
+```
+
+It is a merry dance but the only reliable way to have real testing against a real API.

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/d2l-valence.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'd2l/valence/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'd2l-valence'
+  spec.version       = D2L::Valence::VERSION
+  spec.authors       = ['Michael Harrison']
+  spec.email         = ['michael@ereserve.com.au']
+  spec.summary       = %w(D2L Valence Learning Framework API client for Ruby)
+  spec.description   = %w(A Ruby client for Desire2Learn's Valence Learning Framework APIs primarily used for integration with D2L Brightspace)
+  spec.homepage      = ''
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'rest-client', '~> 2.0.0'
+
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.4.0'
+  spec.add_development_dependency 'rspec-its', '~> 1.2.0'
+  spec.add_development_dependency 'vcr', '~> 3.0.0'
+  spec.add_development_dependency 'webmock', '~> 2.0.0'
+  spec.add_development_dependency 'timecop', '~> 0.8.1'
+end