ruby-office365 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86ee47df4ac96c36024adb5c0595afa78889dc9659aebcdbdf01a59e407a0db9
-  data.tar.gz: 42ab9271c0d32b6035ad9caecc837137774bde57d0894fd49f34782d8c0f1f1b
+  metadata.gz: '0490fef4bbf78efa42231c69e2b12fdb9f12ec37805c5e846225568e85cb03ba'
+  data.tar.gz: a40082526d63f968875194b969146f787de82090207132c69b7d62c344719c6f
 SHA512:
-  metadata.gz: 8dd5a3b6d974b91bf6c2846b1b9b3f433fcc1abe11d6dfc85f3fe3a7b023313db0079b6056a1e27d3d8a36506a434a4ef0e45f327f4d2dd25b0416f681ff5906
-  data.tar.gz: fc2997832814ec584184584546ca7443841914191056f5fd3c080017cf21b273a05f9dd5612b928ad7570fb3cbc202ff0cbaba01e86a62b250c409f1e87776b9
+  metadata.gz: 1a5220233fdf3095a0423a0433b54007ad251cc1bd3dfea051a6c2b2ef3e83586d3142198deda976ffa3425e9c6b97723e0e78af9a564872d2c42e1a9bba7a68
+  data.tar.gz: 445c96c052a74d5ca866769182c98a3da62de4308f83d52db760b5d2bac1fbce3c7be02cdecdfde933ea0d0c3e1c98c264f3175bba68dfbd933c8e29b55f8d15

data/.rubocop.yml

@@ -22,4 +22,7 @@ Metrics/BlockLength:
   Max: 150
 
 Metrics/MethodLength:
-  Max: 50
+  Max: 50
+
+Metrics/CyclomaticComplexity:
+  Max: 20

data/CHANGELOG.md

@@ -15,12 +15,12 @@
 
 - Integrate REST API to get mailbox with pagination
   - get mailbox data with next link `client.messages({next_link: 'xxx'})`
-  - get mailbox data with next link `client.calenders({next_link: 'xxx'})`
+  - get calenders data with next link `client.calenders({next_link: 'xxx'})`
 
 ## [0.1.3] - (2022-10-26)
 
 - Integrate REST API to get contacts
-  - get profile `client.contacts`
+  - get contacts `client.contacts`
   - get contacts data with next link `client.contacts({next_link: 'xxx'})`
 
 ## [0.1.5] - (2022-10-27)
@@ -28,4 +28,16 @@
 - Generate URLs for token and able to refresh token
   - get authorize URL `client.authorize_url`
   - get token URL `client.token_url`
-  - be able to refresh token `client.refresh_token!`
+  - be able to refresh token `client.refresh_token!`
+
+## [0.1.6] - (2022-11-01)
+
+- Integrate REST API to get events
+  - get events `client.events`
+  - get events data with next link `client.events({next_link: 'xxx'})`
+
+## [0.1.7] - (2022-11-11)
+
+- Improve performance: supports select and sort in REST APIs
+  - get messages by select fields `client.messages({ select: %[id] })`
+  - get messages by custom order `client.messages({ order: 'id asc' })`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby-office365 (0.1.5)
+    ruby-office365 (0.1.7)
       faraday
       faraday_middleware
 

data/README.md

@@ -1,8 +1,5 @@
-# Office 365
-
-A simple ruby library to interact with Microsoft Graph and Office 365 API.
-
-- https://developer.microsoft.com/en-us/graph/graph-explorer
+# Office 365 (2022) <img src="https://i.ibb.co/g3mpswn/microsoft-office-365-logo-2016-100727915-large.webp" align="right" width="250" height="150">
+A simple ruby library to interact with Microsoft Graph **[Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer)** and Office 365 API
 
 ## Installation
 
@@ -14,35 +11,57 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install ruby-office365
 
+## Features
+
+- Supports user's mailboxes, calendars, contacts, events
+- Supports refresh token
+
 ## Configuration
 
 You can pass configuration options as a block to `Office365::REST::Client.new`.
 
+- tenant_id: optional, only required for refresh_token
+- client_id: optional, only required for refresh_token
+- client_secret: optional, only required for refresh_token
+- access_token: required for fetch mailbox, calendars, contacts data
+- refresh_token: optional, only required for refresh_token
+- debug: optional, default false, output the request information
+
+### Used to get data from MS Graph API
+
 ```ruby
 client = Office365::REST::Client.new do |config|
-  config.tenant_id          = "YOUR_ORG_TENANT_ID"
-  config.client_id          = "YOUR_APP_CLIENT_ID"
-  config.client_secret      = "YOUR_APP_CLIENT_SECRET"
-  config.redirect_uri       = "YOUR_APP_REDIRECT_URL"
-  config.access_token       = "YOUR_ACCESS_TOKEN"
-  config.refresh_token      = "YOUR_REFRESH_TOKEN"
+  config.access_token = "YOUR_ACCESS_TOKEN"
+  config.debug = "true/false" # Optional, default to false, output the information in the request
 end
 ```
 
-## Usage Examples
+### For refresh token
+
+```ruby
+client = Office365::REST::Client.new do |config|
+  config.tenant_id = "YOUR_ORG_TENANT_ID"
+  config.client_id = "YOUR_APP_CLIENT_ID"
+  config.client_secret = "YOUR_APP_CLIENT_SECRET"
+  config.refresh_token = "YOUR_REFRESH_TOKEN"
+  config.debug = "true/false" # Optional, default to false, output the information in the request
+end
+```
+
+## Usage
 
 After configuring a `client`, you can do the following things.
 
-**response**
+**Response structure**
 
-    - `results`: wrap all data into results
-    - `next_link`: get the new link for the next page of data
+    - results: wrap all data into results
+    - next_link: get the new link for the next page of data
 
-**to JSON**
+**A simple way to convert an office365 object to JSON**
 
-    - `as_json`: convert office365 object to JSON format
+    - as_json: convert office365 object to JSON format
 
-**Get Profile (as the authenticated user)**
+**Get my profile by access token**
 
 ```ruby
 irb(main):004:0> response = client.me
@@ -65,7 +84,7 @@ irb(main):004:0> response.as_json
 }
 ```
 
-**Get my calendars**
+**Get my calendars by access token**
 
 ```ruby
 irb(main):005:0> client.calendars
@@ -73,7 +92,15 @@ irb(main):005:0> client.calendars[:results]
 irb(main):005:0> client.calendars[:next_link]
 ```
 
-**Get my mails**
+**Get my events by access token**
+
+```ruby
+irb(main):005:0> client.events
+irb(main):005:0> client.events[:results]
+irb(main):005:0> client.events[:next_link]
+```
+
+**Get my mails by access token**
 
 ```ruby
 irb(main):005:0> client.messages
@@ -82,7 +109,7 @@ irb(main):005:0> client.messages({ filter: "createdDateTime lt 2022-01-01" })
 irb(main):005:0> client.messages({ filter: "createdDateTime lt 2022-01-01", next_link: 'https://....' })
 ```
 
-**Get my contacts**
+**Get my contacts by access token**
 
 ```ruby
 irb(main):018:0> response = client.contacts
@@ -132,7 +159,7 @@ irb(main):018:0> response[:results][0].as_json
 }
 ```
 
-**Refresh User Token**
+**Refresh access token by refresh token**
 
 ```ruby
 irb(main):005:0> response = client.refresh_token!
@@ -144,6 +171,12 @@ irb(main):005:0> response.refresh_token
 => "0.ARgA7EiQdLv1qECnFqPfrznKsT9ERYaGfG9Ki5WzQtEllj8YAJk.AgABAAEAAAD--DLA3VO7QrddgJg7WevrAgDs_wQA9P-Q1ODlBsrdZi-5s2mfLtEsavBgiEhGcz1KEf26fMrGFU3LM_og5l6wjSAtQ83XHLuje0_KYGol26_LGV_uH0F1MwCFR1N3ctwg4_...."
 ```
 
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
 ## Copyright
 
 Copyright (c) 2022 Encore Shao. See LICENSE for details.

data/lib/office365/models/concerns/base.rb

@@ -6,7 +6,7 @@ module Office365
   module Models
     class Base < OpenStruct
       def initialize(response = {})
-        super(response.transform_keys(&:o_underscore))
+        super(response.transform_keys(&:rails_underscore))
       end
 
       def as_json

data/lib/office365/models/event.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Office365
+  module Models
+    class Event < Base
+      # attr_accessor :id, :subject, :body, :start, :end, :location, :attendees, :organizer
+    end
+  end
+end

data/lib/office365/models.rb

@@ -11,5 +11,6 @@ module Office365
     autoload :EmailAddress,       "office365/models/email_address"
     autoload :Contact,            "office365/models/contact"
     autoload :AccessToken,        "office365/models/access_token"
+    autoload :Event,              "office365/models/event"
   end
 end

data/lib/office365/rest/api.rb

@@ -4,6 +4,7 @@ require_relative "./user"
 require_relative "./mailbox"
 require_relative "./calendar"
 require_relative "./contact"
+require_relative "./event"
 require_relative "./token"
 
 module Office365
@@ -12,6 +13,7 @@ module Office365
       include Office365::REST::User
       include Office365::REST::Mailbox
       include Office365::REST::Calendar
+      include Office365::REST::Event
       include Office365::REST::Contact
       include Office365::REST::Token
     end

data/lib/office365/rest/calendar.rb

@@ -10,12 +10,7 @@ module Office365
       # params: args => { next_link: (nil / next_page_url) }
       # response { results: [], next_link: '...' }
       def calendars(args = {})
-        response = message_response(args: args.merge(base_uri: "/me/calendars"))
-
-        {
-          results: response["value"].map { |v| Models::Calendar.new(v) },
-          next_link: response["@odata.nextLink"]
-        }
+        wrap_results(args.merge(kclass: Models::Calendar, base_uri: "/me/calendars"))
       end
     end
   end

data/lib/office365/rest/concerns/base.rb

@@ -6,21 +6,51 @@ module Office365
       module Base
         private
 
-        def message_response(args: {})
-          next_link = args.delete(:next_link)
+        def wrap_results(args)
+          kclass    = args.delete(:kclass)
+          response  = get_request(args: args)
 
-          request_uri = if next_link
-                          next_link
-                        else
-                          base_uri = args.delete(:base_uri)
+          {
+            results: response["value"].map { |v| kclass.new(v) },
+            next_link: response["@odata.nextLink"]
+          }
+        end
 
-                          req_uri = ["/", Office365::API_VERSION, base_uri].join
-                          req_uri += ["?", args.to_query].join if args.any?
-                          req_uri
-                        end
+        def get_request(args: {})
+          request_uri = parse_and_build_request_url(args)
 
           Request.new(access_token, debug: debug).get(request_uri)
         end
+
+        # https://learn.microsoft.com/en-us/graph/query-parameters?view=graph-rest-1.0
+        # OData system query options
+        # Click the examples to try them in [Graph Explorer](https://developer.microsoft.com/zh-cn/graph/graph-explorer)
+
+        # $count  Retrieves the total count of matching resources.  /me/messages?$top=2&$count=true
+        # $expand Retrieves related resources.  /groups?$expand=members
+        # $filter Filters results (rows). /users?$filter=startswith(givenName,'J')
+        # $format Returns the results in the specified media format.  /users?$format=json
+        # $orderby  Orders results. /users?$orderby=displayName desc
+        # $search Returns results based on search criteria. /me/messages?$search=pizza
+        # $select Filters properties (columns). /users?$select=givenName,surname
+        # $skip Indexes into a result set.
+        #   Also used by some APIs to implement paging and can be used together with $top to manually page results.  /me/messages?$skip=11
+        # $top  Sets the page size of results.  /users?$top=2
+        def parse_and_build_request_url(args)
+          next_link = args.delete(:next_link)
+          return next_link unless next_link.nil?
+
+          # organize params
+          base_uri        = args.delete(:base_uri)
+          select_fields   = args.delete(:select)
+          order_by        = args.delete(:order)
+          args[:select]   = select_fields.map(&:rails_camelize).join(",") if select_fields.is_a?(Array)
+          args[:orderby]  = order_by if order_by
+
+          request_uri = ["/", Office365::API_VERSION, base_uri].join
+          request_uri += ["?", args.to_query].join if args.any?
+          request_uri
+        end
       end
     end
   end

data/lib/office365/rest/contact.rb

@@ -10,12 +10,7 @@ module Office365
       # params: args => { next_link: (nil / next_page_url) }
       # response { results: [], next_link: '...' }
       def contacts(args = {})
-        response = message_response(args: args.merge(base_uri: "/me/contacts"))
-
-        {
-          results: response["value"].map { |v| Models::Contact.new(v) },
-          next_link: response["@odata.nextLink"]
-        }
+        wrap_results(args.merge(kclass: Models::Contact, base_uri: "/me/contacts"))
       end
     end
   end

data/lib/office365/rest/event.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "./concerns/base"
+
+module Office365
+  module REST
+    module Event
+      include Concerns::Base
+
+      # params: args => { next_link: (nil / next_page_url) }
+      # response { results: [], next_link: '...' }
+      def events(args = {})
+        wrap_results(args.merge(kclass: Models::Event, base_uri: "/me/events"))
+      end
+    end
+  end
+end

data/lib/office365/rest/mailbox.rb

@@ -10,12 +10,7 @@ module Office365
       # params: args => { next_link: (nil / next_page_url) }
       # response { results: [], next_link: '...' }
       def messages(args = {})
-        response = message_response(args: args.merge(base_uri: "/me/messages"))
-
-        {
-          results: response["value"].map { |v| Models::Mailbox.new(v) },
-          next_link: response["@odata.nextLink"]
-        }
+        wrap_results(args.merge(kclass: Models::Mailbox, base_uri: "/me/messages"))
       end
     end
   end

data/lib/office365/rest/request.rb

@@ -45,8 +45,14 @@ module Office365
         resp_body = response.body
 
         return resp_body if response.status == 200
-        raise InvalidAuthenticationTokenError, resp_body.dig("error", "message") if response.status == 401
+
         raise InvaliRequestError, resp_body["error_description"] if response.status == 400
+        raise InvalidAuthenticationTokenError, resp_body.dig("error", "message") if response.status == 401
+        raise AccessDeniedError, resp_body.dig("error", "message") if response.status == 403
+        raise NotFoundError, resp_body.dig("error", "message") if response.status == 404
+        raise ThrottlingError, resp_body.dig("error", "message") if response.status == 429
+
+        raise ServiceUnavailableError, resp_body.dig("error", "message") if response.status == 503
 
         raise Error, resp_body["error"]
       end

data/lib/office365/utils/string.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class String
-  def o_underscore
+  def rails_underscore
     gsub(/::/, "/")
       .gsub(/@/, "")
       .gsub(/\./, "_")
@@ -10,4 +10,18 @@ class String
       .tr("-", "_")
       .downcase
   end
+
+  # rubocop:disable Style/SymbolProc
+  def rails_camelize(uppercase_first_letter: false)
+    string = self
+    return string if string !~ /_/ && string =~ /[A-Z]+.*/
+
+    string = if uppercase_first_letter
+               string.sub(/^[a-z\d]*/) { |match| match.capitalize }
+             else
+               string.sub(/^(?:(?=\b|[A-Z_])|\w)/) { |match| match.downcase }
+             end
+    string.gsub(%r{(?:_|(/))([a-z\d]*)}) { "#{::Regexp.last_match(1)}#{::Regexp.last_match(2).capitalize}" }.gsub("/", "::")
+  end
+  # rubocop:enable Style/SymbolProc
 end

data/lib/office365/utils/to_query.rb

@@ -11,7 +11,7 @@ class Object
   # Converts an object into a string suitable for use as a URL query string,
   # using the given <tt>key</tt> as the param name.
   def to_query(key)
-    "#{CGI.escape(key.to_param)}=#{CGI.escape(to_param.to_s)}"
+    "$#{CGI.escape(key.to_param)}=#{CGI.escape(to_param.to_s)}"
   end
 end
 

data/lib/office365/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Office365
-  VERSION = "0.1.5"
+  VERSION = "0.1.7"
 end

data/lib/office365.rb

@@ -12,6 +12,12 @@ module Office365
   class InvalidAuthenticationTokenError < StandardError; end
   class InvaliRequestError < StandardError; end
 
+  # Handling expected errors -> https://learn.microsoft.com/en-us/graph/best-practices-concept#handling-expected-errors
+  class AccessDeniedError < StandardError; end
+  class NotFoundError < StandardError; end
+  class ThrottlingError < StandardError; end
+  class ServiceUnavailableError < StandardError; end
+
   API_HOST      = "https://graph.microsoft.com"
   API_VERSION   = "v1.0"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-office365
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Encore Shao
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-27 00:00:00.000000000 Z
+date: 2022-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -119,6 +119,7 @@ files:
 - lib/office365/models/contact.rb
 - lib/office365/models/directory.rb
 - lib/office365/models/email_address.rb
+- lib/office365/models/event.rb
 - lib/office365/models/mailbox.rb
 - lib/office365/models/owner.rb
 - lib/office365/models/user.rb
@@ -128,6 +129,7 @@ files:
 - lib/office365/rest/client.rb
 - lib/office365/rest/concerns/base.rb
 - lib/office365/rest/contact.rb
+- lib/office365/rest/event.rb
 - lib/office365/rest/mailbox.rb
 - lib/office365/rest/request.rb
 - lib/office365/rest/token.rb
@@ -161,7 +163,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
 summary: A simple ruby library to interact with Microsoft Graph and Office 365 API.