smartsheet 1.0.0.beta.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1cc15ce5cfbb1822363ff37ab362868d9395fcc5
-  data.tar.gz: 245e9e285c496ed02d8449441b020edfaeaa1cee
+  metadata.gz: 10a882532db917a8387dc14379d177779e009ad8
+  data.tar.gz: 7c69eb5bef6f194255a9d40cddb0729d68002b4d
 SHA512:
-  metadata.gz: 33892c0f87e810d3b7a22dd66dbf8f60418717e81f6e962aee171a014845a9f72244525e96087a9d69be00a2087672ca14df55d545a87b244ed43f2651e94d98
-  data.tar.gz: 89778f43258fb0c72aa28a5f3dd2115bfb9ef2a179fcd27e48ba6f649813c1fc9fac06de28cee897714ba316a588d1c15324386e0d457796111a53007373a7e6
+  metadata.gz: 812b0a9e9a550ef012e4b32d270c74fad85f1d72f9a927290726945668ea922c3d05a9e2857a0bca4eacec4e8a81f3b2d44f759d99954da8c2e541448c0ff118
+  data.tar.gz: 78f793670867124aca8184428039b2bc8361a024df856c9f774e5da178c086ed047f2c3e6c8344d603197d3dbcc458171deb1eedf9ec5f05734d554831baa715

data/.yardopts

@@ -0,0 +1,4 @@
+--markup-provider=redcarpet
+--markup=markdown
+-
+README.md

data/README.md

@@ -2,8 +2,6 @@
 
 This is an SDK to simplify connecting to the [Smartsheet API](http://www.smartsheet.com/developers/api-documentation) from Ruby applications.
 
-*Please note that this SDK is beta and may change significantly in the future.*
-
 ## System Requirements
 
 The SDK supports Ruby versions 2.2 or later.
@@ -13,7 +11,7 @@ The SDK supports Ruby versions 2.2 or later.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'smartsheet', '>= 1.0.0.beta'
+gem 'smartsheet', '>= 1.0.0'
 ```
 
 And then execute:
@@ -134,6 +132,9 @@ If you have any questions or issues with this SDK please post on [Stack Overflow
 
 Each specific release is available for download via [GitHub](https://github.com/smartsheet-platform/smartsheet-ruby-sdk/tags).
 
+**v1.0.0 (Nov 2017)**
+Full release
+
 **v1.0.0.beta (October 2017)**
 Beta release of the Smartsheet SDK for Ruby
 

data/Rakefile

@@ -2,12 +2,22 @@ require 'bundler/gem_tasks'
 require 'rake/testtask'
 require 'rubycritic/rake_task'
 
-Rake::TestTask.new(:test) do |t|
+
+Rake::TestTask.new do |t|
   t.libs << 'test'
   t.libs << 'lib'
   t.test_files = FileList['test/**/*_test.rb']
 end
 
+namespace :test do
+  Rake::TestTask.new(:units) do |t|
+    t.libs << 'test'
+    t.pattern = 'test/unit/**/*_test.rb'
+    t.verbose = true
+  end
+end
+
+
 RubyCritic::RakeTask.new
 
 task default: :test

data/lib/smartsheet/api/endpoint_spec.rb

@@ -2,6 +2,7 @@ require_relative 'url_builder'
 
 module Smartsheet
   module API
+    # Specification for a single endpoint's configuration
     class EndpointSpec
       attr_reader :method, :url_segments, :spec
 

data/lib/smartsheet/api/faraday_adapter/faraday_net_client.rb

@@ -5,6 +5,7 @@ require 'smartsheet/api/faraday_adapter/middleware/response_parser'
 
 module Smartsheet
   module API
+    # Makes calls to the Smartsheet API through Faraday
     class FaradayNetClient
       def initialize
         create_connection

data/lib/smartsheet/api/faraday_adapter/faraday_response.rb

@@ -1,30 +1,39 @@
 module Smartsheet
   module API
+    # Builds response objects from Faraday response environments
     class FaradayResponse
-      def self.from_response_env(faraday_response)
-        if faraday_response[:body].kind_of?(Hash) && faraday_response[:body].key?(:errorCode)
-          FaradayErrorResponse.new(faraday_response[:body], faraday_response)
+      def self.from_response_env(faraday_env)
+        if faraday_env[:body].kind_of?(Hash) && faraday_env[:body].key?(:errorCode)
+          FaradayErrorResponse.new(faraday_env[:body], faraday_env)
+        elsif faraday_env.success?
+          FaradaySuccessResponse.new(faraday_env[:body], faraday_env)
         else
-          FaradaySuccessResponse.new(faraday_response[:body], faraday_response)
+          raise HttpResponseError.new(
+              status_code: faraday_env[:status],
+              reason_phrase: faraday_env[:reason_phrase],
+              headers: faraday_env[:response_headers],
+              message: "#{faraday_env[:status]} #{faraday_env[:reason_phrase]}"
+          )
         end
       end
 
       attr_reader :status_code, :reason_phrase, :headers
 
-      def initialize(faraday_response)
-        @status_code = faraday_response[:status]
-        @reason_phrase = faraday_response[:reason_phrase]
-        @headers = faraday_response[:response_headers]
+      def initialize(faraday_env)
+        @status_code = faraday_env[:status]
+        @reason_phrase = faraday_env[:reason_phrase]
+        @headers = faraday_env[:response_headers]
       end
     end
 
+    # Provides a Smartsheet error response from a Faraday response environment
     class FaradayErrorResponse < FaradayResponse
       RETRYABLE_ERRORS = 4001..4004
 
       attr_reader :error_code, :message, :ref_id, :detail
 
-      def initialize(result, faraday_response)
-        super(faraday_response)
+      def initialize(result, faraday_env)
+        super(faraday_env)
         @error_code = result[:errorCode]
         @message = result[:message]
         @ref_id = result[:refId]
@@ -40,11 +49,12 @@ module Smartsheet
       end
     end
 
+    # Provides a Smartsheet success response from a Faraday response environment
     class FaradaySuccessResponse < FaradayResponse
       attr_reader :result
 
-      def initialize(result, faraday_response)
-        super(faraday_response)
+      def initialize(result, faraday_env)
+        super(faraday_env)
         @result = result
       end
 

data/lib/smartsheet/api/faraday_adapter/middleware/faraday_error_translator.rb

@@ -4,6 +4,7 @@ require 'smartsheet/error'
 module Smartsheet
   module API
     module Middleware
+      # Raises Faraday request errors as {Smartsheet::RequestError RequestErrors}
       class FaradayErrorTranslator < Faraday::Middleware
         def initialize(app)
           super(app)

data/lib/smartsheet/api/faraday_adapter/middleware/response_parser.rb

@@ -5,6 +5,7 @@ require 'smartsheet/api/faraday_adapter/faraday_response'
 module Smartsheet
   module API
     module Middleware
+      # Wraps responses into {FaradayResponse FaradayResponses}, parsing JSON bodies when applicable
       class ResponseParser < Faraday::Middleware
         def initialize(app)
           super(app)

data/lib/smartsheet/api/file_spec.rb

@@ -3,6 +3,7 @@ require 'faraday'
 
 module Smartsheet
   module API
+    # Specification for a file attachment by path, target filename, and MIME content type
     class PathFileSpec
       attr_reader :upload_io, :filename, :content_type, :file_length
 
@@ -14,6 +15,8 @@ module Smartsheet
       end
     end
 
+    # Specification for a file attachment by {::File}, target filename, file length, and MIME
+    # content type
     class ObjectFileSpec
       attr_reader :upload_io, :filename, :content_type, :file_length
 

data/lib/smartsheet/api/request.rb

@@ -4,6 +4,7 @@ require 'smartsheet/api/body_builder'
 
 module Smartsheet
   module API
+    # Full specification for a single request to an endpoint
     class Request
       attr_reader :method, :url, :headers, :params, :body
 

data/lib/smartsheet/api/request_client.rb

@@ -2,6 +2,8 @@ require 'smartsheet/error'
 
 module Smartsheet
   module API
+    # Composes {EndpointSpec endpoint specifications} and {RequestSpec request specifications} to
+    # form a single {Request} that it submits to the provided client
     class RequestClient
       def initialize(token, client, base_url, assume_user: nil, logger: MuteRequestLogger.new)
         @token = token

data/lib/smartsheet/api/request_logger.rb

@@ -2,6 +2,7 @@ require 'logger'
 
 module Smartsheet
   module API
+    # Censors strings and hash values for select blacklisted keys
     class Censor
       EXPOSED_CHARS = 4
       KEY_TO_STRING = ->(k){ k.to_s }
@@ -45,6 +46,7 @@ module Smartsheet
       attr_reader :blacklist
     end
 
+    # Logs request and response information, while censoring OAuth-relevant keys
     class RequestLogger
       QUERY_PARAM_CENSOR = Censor.new 'code', 'client_id', 'hash', 'refresh_token'
       HEADER_CENSOR = Censor.new 'authorization'
@@ -80,11 +82,16 @@ module Smartsheet
         log_body('Response', response.result)
       end
 
-      def log_error_response(request, error)
+      def log_api_error_response(request, error)
         log_request_basics(Logger::ERROR, request)
         log_api_error(Logger::ERROR, error)
       end
 
+      def log_http_error_response(request, error)
+        log_request_basics(Logger::ERROR, request)
+        log_http_error(Logger::ERROR, error)
+      end
+
       private
 
       attr_reader :logger, :log_full_body
@@ -112,6 +119,11 @@ module Smartsheet
         log_headers('Response', response)
       end
 
+      def log_http_error(level, response)
+        log_status(level, response)
+        log_headers('Response', response)
+      end
+
       def log_status(level, response)
         logger.log(level) { "Response: #{response.status_code} #{response.reason_phrase}" }
       end
@@ -147,6 +159,7 @@ module Smartsheet
       end
     end
 
+    # Stubs all request logging methods by doing nothing (see {RequestLogger})
     class MuteRequestLogger
       def log_request(request)
       end
@@ -160,7 +173,10 @@ module Smartsheet
       def log_successful_response(response)
       end
 
-      def log_error_response(request, error)
+      def log_api_error_response(request, error)
+      end
+
+      def log_http_error_response(request, error)
       end
     end
   end

data/lib/smartsheet/api/request_spec.rb

@@ -3,6 +3,7 @@ require 'awrence'
 
 module Smartsheet
   module API
+    # Specification for a single API request's arguments
     class RequestSpec
       attr_reader :file_spec, :url_args, :params, :header_overrides, :body, :filename, :content_type
       private :file_spec

data/lib/smartsheet/api/response_net_client_decorator.rb

@@ -4,6 +4,7 @@ require 'smartsheet/error'
 
 module Smartsheet
   module API
+    # Passes requests to the decorated client, and parses responses into expected result types
     class ResponseNetClientDecorator
       def initialize(client, json_output: false, logger: MuteRequestLogger.new)
         @json_output = json_output
@@ -12,7 +13,14 @@ module Smartsheet
       end
 
       def make_request(request)
-        parse(request, client.make_request(request))
+        response = begin
+          client.make_request(request)
+        rescue Smartsheet::HttpResponseError => e
+          logger.log_http_error_response(request, e)
+          raise e
+        end
+
+        parse(request, response)
       end
 
       private
@@ -24,7 +32,7 @@ module Smartsheet
            logger.log_successful_response(response)
            parse_success(response)
          else
-           logger.log_error_response(request, response)
+           logger.log_api_error_response(request, response)
            parse_failure(response)
          end
       end

data/lib/smartsheet/api/retry_logic.rb

@@ -2,6 +2,9 @@ require 'smartsheet/constants'
 
 module Smartsheet
   module API
+    # Accepts a callable proc and a predicate, calling the proc repeatedly with backoff until the
+    # provided time limit is reached, or until the predicate applied to the proc's result returns
+    # false.
     class RetryLogic
       include Smartsheet::Constants
 

data/lib/smartsheet/api/retry_net_client_decorator.rb

@@ -2,6 +2,8 @@ require 'smartsheet/api/request_logger'
 
 module Smartsheet
   module API
+    # Passes requests to the decorated client, retrying the request based on the provided
+    # {RetryLogic} when retry-eligible errors arise
     class RetryNetClientDecorator
       SHOULD_RETRY = ->(response) { response.should_retry? }
 

data/lib/smartsheet/api/url_builder.rb

@@ -2,7 +2,7 @@ require 'smartsheet/constants'
 
 module Smartsheet
   module API
-    # Methods for building Smartsheet API URLs
+    # Constructs parameterized URLs for accessing the Smartsheet API
     class UrlBuilder
       def initialize(endpoint_spec, request_spec, base_url)
         @segments = endpoint_spec.url_segments

data/lib/smartsheet/client.rb

@@ -25,6 +25,41 @@ require 'smartsheet/endpoints/workspaces/workspaces'
 
 
 module Smartsheet
+  # The entry point to the SDK. API endpoint categories are accessed through this object's readable
+  # attributes.
+  #
+  # @!attribute [r] contacts
+  #   @return [Contacts]
+  # @!attribute [r] favorites
+  #   @return [Favorites]
+  # @!attribute [r] folders
+  #   @return [Folders]
+  # @!attribute [r] groups
+  #   @return [Groups]
+  # @!attribute [r] home
+  #   @return [Home]
+  # @!attribute [r] reports
+  #   @return [Reports]
+  # @!attribute [r] search
+  #   @return [Search]
+  # @!attribute [r] server_info
+  #   @return [ServerInfo]
+  # @!attribute [r] sheets
+  #   @return [Sheets]
+  # @!attribute [r] sights
+  #   @return [Sights]
+  # @!attribute [r] templates
+  #   @return [Templates]
+  # @!attribute [r] token
+  #   @return [Token]
+  # @!attribute [r] update_requests
+  #   @return [UpdateRequests]
+  # @!attribute [r] users
+  #   @return [Users]
+  # @!attribute [r] webhooks
+  #   @return [Webhooks]
+  # @!attribute [r] workspaces
+  #   @return [Workspaces]
   class Client
     include GeneralRequest
     include Smartsheet::Constants
@@ -33,14 +68,40 @@ module Smartsheet
                 :sheets, :sights, :templates, :token, :update_requests, :users, :webhooks,
                 :workspaces
 
+    # @param token [String] access token for the API; if nil or empty, uses environment variable
+    #   `SMARTSHEET_ACCESS_TOKEN`
+    # @param logger [Logger] a logger to which request and response info will be recorded
+    # @param log_full_body [Boolean] when true, request and response bodies will not be truncated in
+    #   the logs
+    # @param json_output [Boolean] when true, endpoints return raw JSON strings instead of hashes
+    # @param assume_user [String] the email address of the user to impersonate; only available for
+    #   admin roles
+    # @param max_retry_time [Fixnum] overrides the maximum number of seconds during which eligible
+    #   errors will be retried
+    # @param backoff_method [Proc] overrides the backoff calculation method, accepting the index of
+    #   the current retry attempt (0-based) and returning the number of seconds to wait before
+    #   retrying the call again, or `:stop` to halt retrying and return the latest error.
+    #
+    #   Example - Wait 1 second before the first retry, 2 seconds before
+    #   the second, and so on:
+    #   ```ruby
+    #   ->(x){ x + 1 }
+    #   ```
+    #
+    #   Example - Try twice, then halt:
+    #   ```ruby
+    #   ->(x){ if x < 2 then x + 1 else :stop end }
+    #   ```
+    # @param base_url [String] overrides the base URL used when constructing API calls; for example,
+    #   the default takes the form of `https://api.smartsheet.com/2.0`
     def initialize(
         token: nil,
-        assume_user: nil,
+        logger: nil,
+        log_full_body: false,
         json_output: false,
+        assume_user: nil,
         max_retry_time: nil,
         backoff_method: nil,
-        logger: nil,
-        log_full_body: false,
         base_url: API_URL
     )
 
@@ -74,7 +135,6 @@ module Smartsheet
           assume_user: assume_user,
           logger: request_logger
       )
-
       build_categories
     end
 

data/lib/smartsheet/constants.rb

@@ -1,6 +1,6 @@
 module Smartsheet
   module Constants
-    VERSION = '1.0.0.beta.2'.freeze
+    VERSION = '1.0.0'.freeze
 
     USER_AGENT = 'smartsheet-ruby-sdk'.freeze
     API_URL = 'https://api.smartsheet.com/2.0'.freeze

data/lib/smartsheet/endpoints/contacts/contacts.rb

@@ -1,4 +1,6 @@
 module Smartsheet
+  # Contacts Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#contacts API Contacts Docs
   class Contacts
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/favorites/favorites.rb

@@ -1,4 +1,6 @@
 module Smartsheet
+  # Favorites Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#favorites API Favorites Docs
   class Favorites
     attr_reader :client
     private :client
@@ -55,7 +57,7 @@ module Smartsheet
 
     def remove_sight(sight_id:, params: {}, header_overrides: {})
       remove_favorite(
-          url: ['sights', :sight_id],
+          url: ['sight', :sight_id],
           params: params,
           header_overrides: header_overrides,
           sight_id: sight_id
@@ -109,7 +111,7 @@ module Smartsheet
 
     def remove_sights(sight_ids:, params: {}, header_overrides: {})
       remove_favorites(
-          url: ['sights'],
+          url: ['sight'],
           params: params,
           header_overrides: header_overrides,
           object_ids: sight_ids

data/lib/smartsheet/endpoints/folders/folders.rb

@@ -1,4 +1,6 @@
 module Smartsheet
+  # Folders Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#folders API Folders Docs
   class Folders
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/groups/groups.rb

@@ -1,4 +1,6 @@
 module Smartsheet
+  # Groups Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#groups API Groups Docs
   class Groups
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/home/home.rb

@@ -1,4 +1,6 @@
 module Smartsheet
+  # Home Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#home API Home Docs
   class Home
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/reports/reports.rb

@@ -3,6 +3,11 @@ require 'smartsheet/constants'
 require_relative 'reports_share'
 
 module Smartsheet
+  # Reports Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#reports API Reports Docs
+  #
+  # @!attribute [r] share
+  #   @return [ReportsShare]
   class Reports
     include Smartsheet::Constants
 

data/lib/smartsheet/endpoints/reports/reports_share.rb

@@ -1,6 +1,8 @@
 require 'smartsheet/endpoints/share/share'
 
 module Smartsheet
+  # Report Sharing Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#report-sharing API Report Sharing Docs
   class ReportsShare
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/search/search.rb

@@ -1,4 +1,6 @@
 module Smartsheet
+  # Search Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#search API Search Docs
   class Search
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/server_info/server_info.rb

@@ -1,4 +1,7 @@
 module Smartsheet
+  # Server Information Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#server-information API Server
+  #   Information Docs
   class ServerInfo
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/share/share.rb

@@ -1,4 +1,5 @@
 module Smartsheet
+  # Sharing Endpoints Mixin
   module Share
     def delete_share(share_id:, url:, params:, header_overrides:, **url_args)
       endpoint_spec = Smartsheet::API::EndpointSpec.new(:delete, url + ['shares', :share_id])

data/lib/smartsheet/endpoints/sheets/cells.rb

@@ -1,6 +1,8 @@
 require 'smartsheet/api/file_spec'
 
 module Smartsheet
+  # Cells Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#cells API Cells Docs
   class Cells
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/sheets/columns.rb

@@ -1,4 +1,6 @@
 module Smartsheet
+  # Columns Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#columns API Columns Docs
   class Columns
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/sheets/comments.rb

@@ -1,6 +1,11 @@
 require 'smartsheet/endpoints/sheets/comments_attachments'
 
 module Smartsheet
+  # Comments Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#comments API Comments Docs
+  #
+  # @!attribute [r] attachments
+  #   @return [CommentsAttachments]
   class Comments
     attr_reader :client, :attachments
     private :client

data/lib/smartsheet/endpoints/sheets/comments_attachments.rb

@@ -1,6 +1,8 @@
 require 'smartsheet/api/file_spec'
 
 module Smartsheet
+  # Comments Attachments Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#attachments API Attachments Docs
   class CommentsAttachments
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/sheets/discussions.rb

@@ -1,6 +1,11 @@
 require 'smartsheet/endpoints/sheets/discussions_attachments'
 
 module Smartsheet
+  # Discussions Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#discussions API Discussions Docs
+  #
+  # @!attribute [r] attachments
+  #   @return [DiscussionsAttachments]
   class Discussions
     attr_reader :client, :attachments
     private :client

data/lib/smartsheet/endpoints/sheets/discussions_attachments.rb

@@ -1,4 +1,6 @@
 module Smartsheet
+  # Discussions Attachments Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#attachments API Attachments Docs
   class DiscussionsAttachments
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/sheets/rows.rb

@@ -1,6 +1,11 @@
 require 'smartsheet/endpoints/sheets/rows_attachments'
 
 module Smartsheet
+  # Rows Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#rows API Rows Docs
+  #
+  # @!attribute [r] attachments
+  #   @return [RowsAttachments]
   class Rows
     attr_reader :client, :attachments
     private :client

data/lib/smartsheet/endpoints/sheets/rows_attachments.rb

@@ -1,6 +1,8 @@
 require 'smartsheet/api/file_spec'
 
 module Smartsheet
+  # Rows Attachments Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#attachments API Attachments Docs
   class RowsAttachments
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/sheets/sheets.rb

@@ -11,7 +11,23 @@ require 'smartsheet/endpoints/sheets/sheets_attachments'
 require 'smartsheet/endpoints/sheets/sheets_share'
 
 module Smartsheet
-  # Sheet resource endpoints
+  # Sheets Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#sheets API Sheets Docs
+  #
+  # @!attribute [r] attachments
+  #   @return [SheetsAttachments]
+  # @!attribute [r] cells
+  #   @return [Cells]
+  # @!attribute [r] columns
+  #   @return [Columns]
+  # @!attribute [r] comments
+  #   @return [Comments]
+  # @!attribute [r] discussions
+  #   @return [Discussions]
+  # @!attribute [r] rows
+  #   @return [Rows]
+  # @!attribute [r] share
+  #   @return [SheetsShare]
   class Sheets
     include Smartsheet::Constants
 

data/lib/smartsheet/endpoints/sheets/sheets_attachments.rb

@@ -1,6 +1,8 @@
 require 'smartsheet/api/file_spec'
 
 module Smartsheet
+  # Sheet Attachments Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#attachments API Attachments Docs
   class SheetsAttachments
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/sheets/sheets_share.rb

@@ -1,6 +1,8 @@
 require 'smartsheet/endpoints/share/share'
 
 module Smartsheet
+  # Sheet Sharing Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#sheet-sharing API Sheet Sharing Docs
   class SheetsShare
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/sights/sights.rb

@@ -1,6 +1,11 @@
 require_relative 'sights_share'
 
 module Smartsheet
+  # Sights Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#sights API Sights Docs
+  #
+  # @!attribute [r] share
+  #   @return [SightsShare]
   class Sights
     attr_reader :client, :share
     private :client

data/lib/smartsheet/endpoints/sights/sights_share.rb

@@ -1,6 +1,8 @@
 require 'smartsheet/endpoints/share/share'
 
 module Smartsheet
+  # Sight Sharing Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#sight-sharing API Sight Sharing Docs
   class SightsShare
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/templates/templates.rb

@@ -1,4 +1,6 @@
 module Smartsheet
+  # Templates Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#templates API Templates Docs
   class Templates
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/token/token.rb

@@ -1,6 +1,10 @@
 require 'digest'
 
 module Smartsheet
+  # Token Endpoints
+  #
+  # {#get} and {#refresh} do not require an existing token to call
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#token API Token Docs
   class Token
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/update_requests/sent_update_requests.rb

@@ -1,4 +1,7 @@
 module Smartsheet
+  # Sent Update Requests Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#update-requests API Update Requests
+  #   Docs
   class SentUpdateRequests
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/update_requests/update_requests.rb

@@ -1,6 +1,12 @@
 require 'smartsheet/endpoints/update_requests/sent_update_requests'
 
 module Smartsheet
+  # Update Requests Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#update-requests API Update Requests
+  #   Docs
+  #
+  # @!attribute [r] sent
+  #   @return [SentUpdateRequests]
   class UpdateRequests
     attr_reader :client, :sent
     private :client

data/lib/smartsheet/endpoints/users/alternate_emails.rb

@@ -1,4 +1,7 @@
 module Smartsheet
+  # Alternate Emails Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#alternate-email-addresses API
+  #   Alternate Email Addresses Docs
   class AlternateEmails
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/users/users.rb

@@ -1,6 +1,11 @@
 require_relative 'alternate_emails'
 
 module Smartsheet
+  # Users Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#users API Users Docs
+  #
+  # @!attribute [r] alternate_emails
+  #   @return [AlternateEmails]
   class Users
     attr_reader :client, :alternate_emails
     private :client

data/lib/smartsheet/endpoints/webhooks/webhooks.rb

@@ -1,4 +1,6 @@
 module Smartsheet
+  # Webhooks Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#webhooks-reference API Webhooks Docs
   class Webhooks
     attr_reader :client
     private :client

data/lib/smartsheet/endpoints/workspaces/workspaces.rb

@@ -1,6 +1,11 @@
 require_relative 'workspaces_share'
 
 module Smartsheet
+  # Workspaces Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#workspaces API Workspaces Docs
+  #
+  # @!attribute [r] share
+  #   @return [WorkspacesShare]
   class Workspaces
     attr_reader :client, :share
     private :client

data/lib/smartsheet/endpoints/workspaces/workspaces_share.rb

@@ -1,6 +1,9 @@
 require 'smartsheet/endpoints/share/share'
 
 module Smartsheet
+  # Workspace Sharing Endpoints
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#workspace-sharing API Workspace
+  #   Sharing Docs
   class WorkspacesShare
     attr_reader :client
     private :client

data/lib/smartsheet/error.rb

@@ -1,6 +1,7 @@
 require 'forwardable'
 
 module Smartsheet
+  # Top-level Smartsheet Error
   class Error < StandardError; end
 
   # Errors for invalid requests, timeouts, etc.
@@ -13,11 +14,50 @@ module Smartsheet
     end
   end
 
-  class ApiError < Error
+  # Errors for generic HTTP error codes
+  # @!attribute [r] status_code
+  #   @return [Fixnum] HTTP status code
+  # @!attribute [r] reason_phrase
+  #   @return [String] HTTP reason phrase
+  # @!attribute [r] headers
+  #   @return [Hash] HTTP response headers
+  class HttpResponseError < Error
+    attr_reader :status_code, :reason_phrase, :headers
+
+    def initialize(status_code:, reason_phrase:, headers:, message:)
+      super(message)
+
+      @status_code = status_code
+      @reason_phrase = reason_phrase
+      @headers = headers
+    end
+  end
+
+  # Errors for Smartsheet API error objects
+  # @see https://smartsheet-platform.github.io/api-docs/?ruby#error-object API Error Object Docs
+  #
+  # @!attribute [r] error_code
+  #   @return [Fixnum] Smartsheet error code
+  #   @see https://smartsheet-platform.github.io/api-docs/?ruby#complete-error-code-list API Error
+  #     Code Docs
+  # @!attribute [r] message
+  #   @return [String] Smartsheet error message
+  #   @see https://smartsheet-platform.github.io/api-docs/?ruby#complete-error-code-list API Error
+  #     Code Docs
+  # @!attribute [r] ref_id
+  #   @return [String] Smartsheet error reference ID
+  # @!attribute [r] detail
+  #   @return [Hash, Array, nil] optional details for some error scenarios
+  class ApiError < HttpResponseError
     extend Forwardable
 
     def initialize(error_response)
-      super(error_response.message)
+      super(
+          status_code: error_response.status_code,
+          reason_phrase: error_response.reason_phrase,
+          headers: error_response.headers,
+          message: error_response.message
+      )
       @error_response = error_response
     end
 

data/lib/smartsheet/general_request.rb

@@ -2,6 +2,9 @@ require 'smartsheet/api/file_spec'
 
 module Smartsheet
   module GeneralRequest
+    # Create a custom request using a provided method and URL path
+    # @example Make a GET request to 'https://api.smartsheet.com/2.0/sheets/list'
+    #   client.request(method: :get, url_path: 'sheets/list')
     def request(method:, url_path:, body: nil, params: {}, header_overrides: {})
       spec = body.nil? ? {} : {body_type: :json}
       endpoint_spec = Smartsheet::API::EndpointSpec.new(method, [url_path], **spec)
@@ -13,6 +16,16 @@ module Smartsheet
       client.make_request(endpoint_spec, request_spec)
     end
 
+    # Create a custom request using a provided method, URL path, and file details
+    # @example Make a POST request to 'https://api.smartsheet.com/2.0/sheets/1/attachments' with a file
+    #   client.request_with_file(
+    #     method: :get,
+    #     url_path: 'sheets/1/attachments',
+    #     file: File.open('my-file.docx'),
+    #     file_length: 1000,
+    #     filename: 'my-uploaded-file.docx',
+    #     content_type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+    #   )
     def request_with_file(
         method:,
         url_path:,
@@ -32,6 +45,15 @@ module Smartsheet
       client.make_request(endpoint_spec, request_spec)
     end
 
+    # Create a custom request using a provided method, URL path, and filepath details
+    # @example Make a POST request to 'https://api.smartsheet.com/2.0/sheets/1/attachments' with a file
+    #   client.request_with_file_from_path(
+    #     method: :get,
+    #     url_path: 'sheets/1/attachments',
+    #     path: './my-file.docx',
+    #     filename: 'my-uploaded-file.docx',
+    #     content_type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+    #   )
     def request_with_file_from_path(
         method:,
         url_path:,

data/smartsheet.gemspec

@@ -14,7 +14,6 @@ Gem::Specification.new do |spec|
   spec.description   = <<-EOF
     This is an SDK to simplify connecting to the Smartsheet API
     (http://www.smartsheet.com/developers/api-documentation) from Ruby applications.
-    Please note that this SDK is beta and may change significantly in the future.
   EOF
   spec.homepage      = 'https://github.com/smartsheet-platform/smartsheet-ruby-sdk'
   spec.license       = 'Apache-2.0'
@@ -32,7 +31,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = '> 2.2'
+  spec.required_ruby_version = '~> 2.2'
 
   spec.add_dependency 'faraday', '~> 0.13.1'
   spec.add_dependency 'plissken', '~> 1.2'
@@ -47,4 +46,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop', '~> 0.49.1'
   spec.add_development_dependency 'reek', '~> 4.7'
   spec.add_development_dependency 'rubycritic', '~> 3.2'
+  spec.add_development_dependency 'yard', '~> 0.9'
+  spec.add_development_dependency 'redcarpet', '~> 3.4'
+  spec.add_development_dependency 'github-markup', '~> 1.6'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: smartsheet
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Smartsheet
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-10-12 00:00:00.000000000 Z
+date: 2017-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -178,10 +178,51 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: github-markup
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
 description: |2
       This is an SDK to simplify connecting to the Smartsheet API
       (http://www.smartsheet.com/developers/api-documentation) from Ruby applications.
-      Please note that this SDK is beta and may change significantly in the future.
 email: api@smartsheet.com
 executables: []
 extensions: []
@@ -190,6 +231,7 @@ files:
 - ".gitignore"
 - ".rubocop.yml"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE
 - README.md
@@ -261,14 +303,14 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - "~>"
     - !ruby/object:Gem::Version
       version: '2.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.6.8