sheets_v4 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea8bb19ec472d573c796d277e420c088273c087aa9ffe4ebbb63df0a2ffb69ae
-  data.tar.gz: 5a2dca82c26a9efdd7584a5c33f4e4d9bfa1f8ac0003cf504d936554e6bb9f7d
+  metadata.gz: b3ed35f7562643f623e68d6ad41c497f1d92ea7b2d77f4b6f0d5e02586109897
+  data.tar.gz: 6687dfc41d70870694a2085e749d803f7062de8d2486866e4e44ea54b1eec95f
 SHA512:
-  metadata.gz: 0676d4dcff6bd008104638a1a593cfcf638ad990d15a6f1a2f71cba44e0a387e5c3e527978cb3fc9e0517ecf9ef35dd8fac2348ac993f58f28147769261d3412
-  data.tar.gz: ab5ae3a72384e45ee10411d1f1a89231ef9092393e686e81b0cb9e7734b216c039589697f2ef5e7d3313b677f5ea022ac8b2135adaa57e7e01c6032a12de0bb0
+  metadata.gz: 00334f58b9080916f1239671e106292742a00bbd931582577ae8a0664c25ea83f1ecaf5154996a0f28deffe9e8aaf58e4963dd94160095853d7d3454ef9e1b82
+  data.tar.gz: a89714057c1aa145ce2b5eaa5a05776b8593c76d6e944b1b2b868b1ddd16a4247bf05ac13b218b74addb0204a3644cb6657e30e2331e725ca68467359cfd66a9

data/CHANGELOG.md

@@ -4,6 +4,25 @@ Changes for each release are listed in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/) for its releases.
 
+## v0.7.0 (2023-10-08)
+
+[Full Changelog](https://github.com/main-branch/sheets_v4/compare/v0.6.0..v0.7.0)
+
+Changes since v0.6.0:
+
+* 616fe1f Add conversions bewteen Date/DateTime and spreadsheet values (#22)
+* 6f37337 Rename SheetsV4::ValidateApiObjects to SheetsV4::ApiObjectValidation (#21)
+* 0f76992 Rename SheetsV4::ValidateApiObjects::Validate to SheetsV4::ValidateApiObjects::ValidateApiObject (#20)
+* e80040c Rename SheetsV4::CredentialCreator to SheetsV4::CreateCredential (#19)
+
+## v0.6.0 (2023-10-03)
+
+[Full Changelog](https://github.com/main-branch/sheets_v4/compare/v0.5.0..v0.6.0)
+
+Changes since v0.5.0:
+
+* 2eab61d Update documentation explaining how to construct and validate a request (#17)
+
 ## v0.5.0 (2023-10-01)
 
 [Full Changelog](https://github.com/main-branch/sheets_v4/compare/v0.4.0..v0.5.0)

data/README.md

@@ -9,29 +9,52 @@
 
 Unofficial helpers for the Google Sheets V4 API
 
-* [Important Links for Programming Google Sheets](#important-links-for-programming-google-sheets)
-  * [General API Documentation](#general-api-documentation)
-  * [Ruby Implementation of the Sheets API](#ruby-implementation-of-the-sheets-api)
-  * [Other Links](#other-links)
 * [Installation](#installation)
+* [Important links for programming Google Sheets](#important-links-for-programming-google-sheets)
+  * [General API documentation](#general-api-documentation)
+  * [Ruby implementation of the Sheets API](#ruby-implementation-of-the-sheets-api)
+  * [Other Links](#other-links)
+* [Getting Started](#getting-started)
+  * [Creating a Google Cloud project](#creating-a-google-cloud-project)
+  * [Enable the APIs you want to use](#enable-the-apis-you-want-to-use)
+  * [Create a Google API credentials](#create-a-google-api-credentials)
 * [Usage](#usage)
   * [Obtaining an authenticated SheetsService](#obtaining-an-authenticated-sheetsservice)
+  * [Building a request](#building-a-request)
+    * [Method 1: constructing requests using `Google::Apis::SheetsV4::*` objects](#method-1-constructing-requests-using-googleapissheetsv4-objects)
+    * [Method 2: constructing requests using hashes](#method-2-constructing-requests-using-hashes)
+    * [Which method should be used?](#which-method-should-be-used)
+  * [Validating requests](#validating-requests)
+  * [Working with dates and times](#working-with-dates-and-times)
   * [Colors](#colors)
 * [Development](#development)
-* [Creating a Google API Service Account](#creating-a-google-api-service-account)
 * [Contributing](#contributing)
 * [License](#license)
 
-## Important Links for Programming Google Sheets
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```shell
+bundle add sheets_v4
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
 
-### General API Documentation
+```shell
+gem install sheets_v4
+```
+
+## Important links for programming Google Sheets
+
+### General API documentation
 
 * [Google Sheets API Overview](https://developers.google.com/sheets/api)
 * [Google Sheets API Reference](https://developers.google.com/sheets/api/reference/rest)
 * [Batch Update Requests](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request)
 * [Discovery Document for the Sheets API](https://sheets.googleapis.com/$discovery/rest?version=v4)
 
-### Ruby Implementation of the Sheets API
+### Ruby implementation of the Sheets API
 
 * [SheetsService Class](https://github.com/googleapis/google-api-ruby-client/blob/main/generated/google-apis-sheets_v4/lib/google/apis/sheets_v4/service.rb)
 * [All Other Sheets Classes](https://github.com/googleapis/google-api-ruby-client/blob/main/generated/google-apis-sheets_v4/lib/google/apis/sheets_v4/classes.rb)
@@ -40,19 +63,25 @@ Unofficial helpers for the Google Sheets V4 API
 
 * [Apps Script for Sheets](https://developers.google.com/apps-script/guides/sheets)
 
-## Installation
+## Getting Started
 
-Install the gem and add to the application's Gemfile by executing:
+In order to use this gem, you will need to obtain a Google API sheets service
+credential following the instructions below.
 
-```shell
-bundle add sheets_v4
-```
+### Creating a Google Cloud project
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Create a Google Cloud project using [these directions](https://developers.google.com/workspace/guides/create-project).
 
-```shell
-gem install sheets_v4
-```
+### Enable the APIs you want to use
+
+Enable the Sheets API for this project using [these directions](https://developers.google.com/workspace/guides/enable-apis).
+
+### Create a Google API credentials
+
+Create a service account and download credentials using [these directions](https://developers.google.com/workspace/guides/create-credentials#service-account).
+
+You can store the download credential files anywhere on your system. The recommended
+location is `~/.google-api-credential.json`.
 
 ## Usage
 
@@ -86,18 +115,227 @@ If the credential is stored elsewhere, pass the credential_source to `SheetsV4.s
 manually. `credential_source` can be a String:
 
 ```Ruby
-sheets_service = SheetsV4.sheets_service(credential_sourvce: File.read('credential.json'))
+sheets_service = SheetsV4.sheets_service(credential_source: File.read('credential.json'))
 ```
 
 an IO object:
 
 ```Ruby
 sheets_service = File.open('credential.json') do |credential_source|
-  SheetsV4.sheets_service(credential_sourvce:)
+  SheetsV4.sheets_service(credential_source:)
+end
+```
+
+or an already constructed `Google::Auth::*` object.
+
+### Building a request
+
+To use the Sheets API, you need to construct JSON formatted requests.
+
+These requests can be constructed using two different methods:
+1. constructing requests using `Google::Apis::SheetsV4::*` objects or
+2. constructing requests using hashes
+
+The following two sections show how each method can be used to construct
+a request to update a row of values in a sheet.
+
+For these two examples, values in the `values` array will be written to the
+sheet whose ID is 0. The values will be written one per row starting at cell A1.
+
+```Ruby
+values = %w[one two three four] # 'one' goes in A1, 'two' goes in A2, etc.
+```
+
+The method `SheetsService#batch_update_spreadsheet` will be used to write the values. This
+method takes a `batch_update_spreadsheet_request` object with a `update_cells` request
+that defines the update to perform.
+
+#### Method 1: constructing requests using `Google::Apis::SheetsV4::*` objects
+
+When using this method, keep the Ruby source file containing the SheetsService class
+([google/apis/sheets_v4/service.rb](https://github.com/googleapis/google-api-ruby-client/blob/main/generated/google-apis-sheets_v4/lib/google/apis/sheets_v4/service.rb))
+and the Ruby source file containing the defitions of the request & data classes
+([lib/google/apis/sheets_v4/classes.rb](https://github.com/googleapis/google-api-ruby-client/blob/main/generated/google-apis-sheets_v4/lib/google/apis/sheets_v4/classes.rb))
+open for easy searching. These files will give you all the information you need
+to construct valid requests.
+
+Here is the example constructing requests using `Google::Apis::SheetsV4::*` objects
+
+```Ruby
+def values = %w[one two three four]
+
+def row_data(value)
+  Google::Apis::SheetsV4::RowData.new(
+    values: [
+      Google::Apis::SheetsV4::CellData.new(
+        user_entered_value:
+          Google::Apis::SheetsV4::ExtendedValue.new(string_value: value.to_s)
+      )
+    ]
+  )
+end
+
+def rows
+  values.map { |value| row_data(value) }
+end
+
+def write_values_request
+  fields = 'user_entered_value'
+  start = Google::Apis::SheetsV4::GridCoordinate.new(
+    sheet_id: 0, row_index: 0, column_index: 0
+  )
+  Google::Apis::SheetsV4::Request.new(
+    update_cells: Google::Apis::SheetsV4::UpdateCellsRequest.new(rows:, fields:, start:)
+  )
+end
+
+requests = Google::Apis::SheetsV4::BatchUpdateSpreadsheetRequest.new(requests: [write_values_request])
+
+spreadsheet_id = '18FAcgotK7nDfLTOTQuGCIjKwxkJMAguhn1OVzpFFgWY'
+SheetsV4.sheets_service.batch_update_spreadsheet(spreadsheet_id, requests)
+```
+
+#### Method 2: constructing requests using hashes
+
+When constructing requests using this method, keep the [Google Sheets Rest API Reference](https://developers.google.com/sheets/api/reference/rest)
+documentation open. In particular, [the Batch Update Requests page](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#cutpasterequest)
+is particularly useful for building spreadsheet batch update requests.
+
+One caveat to keep in mind is that the Rest API documents object properties using
+Camel case BUT the Ruby API requires snake case.
+
+For instance, the Rest API documents the properties for a grid coordinate to be
+"sheetId", "rowIndex", and "columnIndex". However, in the Ruby API, you should
+construct this object using snake case:
+
+```Ruby
+grid_coordinate = { sheet_id: 0, row_index: 0, column_index: 0 }
+```
+
+Here is the example constructing requests using hashes:
+
+```Ruby
+def values = %w[one two three four]
+
+def rows
+  values.map do |value|
+    { values: [{ user_entered_value: { string_value: value } }] }
+  end
+end
+
+def write_values_request
+  fields = 'user_entered_value'
+  start = { sheet_id: 0, row_index: 0, column_index: 0 }
+  { update_cells: { rows:, fields:, start: } }
 end
+
+requests = { requests: [write_values_request] }
+
+spreadsheet_id = '18FAcgotK7nDfLTOTQuGCIjKwxkJMAguhn1OVzpFFgWY'
+response = SheetsV4.sheets_service.batch_update_spreadsheet(spreadsheet_id, requests)
 ```
 
-or an already constructed `Google::Auth::*`` object.
+#### Which method should be used?
+
+Either method will do the same job. I prefer "Method 2: constructing requests using
+hashes" because my code is more concise and easy to read.
+
+While either method can produce a malformed request, "Method 2" is more likely to
+result in malformed requests. Unfortunately, when given a malformed request, the
+Google Sheets API will do one of following depending on the nature of the problem:
+
+1. Raise a `Google::Apis::ClientError` with some additional information
+2. Raise a `Google::Apis::ClientError` with no additional information (this the most
+   common result)
+3. Not return an error with some of the batch requests not having the expected outcome
+
+Luckily, this library provides a way to validate that requests are valid and
+identifies precisely where the request objects do not conform to the API description.
+That is the subject of the next section [Validating requests](#validating-requests).
+
+### Validating requests
+
+The [`SheetsV4.validate_api_object`](https://rubydoc.info/gems/sheets_v4/SheetsV4#validate_api_object-class_method)
+method can be used to validate request objects prior to using them in the Google
+Sheets API.
+
+This method takes a `schema_name` and an `object` to validate. Schema names can be
+listed using [`SheetsV4.api_object_schema_names`](https://rubydoc.info/gems/sheets_v4/SheetsV4#api_object_schema_names-class_method).
+
+This method will either return `true` if `object` conforms to the schema OR it
+will raise a RuntimeError noting where the object structure did not conform to
+the schema.
+
+In the previous examples (see [Building a request](#building-a-request)), the
+following line can be inserted after the `requests =  ...` line to validate the
+request:
+
+```Ruby
+SheetsV4.validate_api_object(schema: 'batch_update_spreadsheet_request', object: requests)
+```
+
+### Working with dates and times
+
+Google Sheets, similar to other spreadsheet programs, stores dates and date-time
+values as numbers. This system makes it easier to perform calculations with
+dates and times.
+
+This gem provides two sets of equavalent conversion methods. The first set is defined
+as class methods on the `SheetsV4` class.
+
+* `SheetsV4.date_to_gs(date)` returns a numeric cell value
+* `SheetsV4.gs_to_date(cell_value)` returns a Date object
+* `SheetsV4.datetime_to_gs(datetime)` returns a numeric cell value
+* `SheetsV4.gs_to_datetime(cell_value)` returns a DateTime object
+
+In order to convert to and from spreadsheet values, the spreadsheet timezone must
+be known. A spreadsheet's timezone is found in the Google Sheets spreadsheet object's
+properties:
+
+```Ruby
+SheetsV4.default_spreadsheet_tz = spreadsheet.properties.time_zone
+```
+
+If a time zone is not set using `SheetsV4.default_spreadsheet_tz`, a RuntimeError
+will be raised when any of the above methods are used.
+
+Here is an example of how the timezone can change the values fetched from the
+spreadsheet:
+
+```Ruby
+cell_value = 44333.191666666666
+
+SheetsV4.default_spreadsheet_tz = 'America/New_York'
+datetime = SheetsV4.gs_to_datetime(cell_value) #=> Mon, 17 May 2021 04:36:00 -0400
+datetime.utc #=> 2021-05-17 08:36:00 UTC
+
+SheetsV4.default_spreadsheet_tz = 'America/Los_Angeles'
+datetime = SheetsV4.gs_to_datetime(cell_value) #=> Mon, 17 May 2021 04:36:00 -0700
+datetime.utc #=> 2021-05-17 11:36:00 UTC
+```
+
+Valid time zone names are those listed in one of these two sources:
+
+* `ActiveSupport::TimeZone.all.map { |tz| tz.tzinfo.name }`
+* `ActiveSupport::TimeZone.all.map(&:name)`
+
+The `SheetsV4` methods works well if the spreadsheet timezone is constant through
+the run of the program. If this is not the case -- for instance when working with
+multiple spreadsheets whose timezones may be different -- then use
+`SheetsV4::ConvertDatesAndTimes`.
+
+Each instance of `SheetsV4::ConvertDatesAndTimes` has it's own spreadsheet timezone
+used in the conversions. Instance methods for this class are the same as the
+date conversion methods on the SheetsV4 class.
+
+Example:
+
+```Ruby
+cell_value = 44333.191666666666
+converter = SheetsV4::ConvertDatesAndTimes.new('America/Los_Angeles')
+datetime = SheetsV4.gs_to_datetime(cell_value) #=> Mon, 17 May 2021 04:36:00 -0700
+datetime.utc #=> 2021-05-17 11:36:00 UTC
+```
 
 ### Colors
 
@@ -114,8 +352,8 @@ SheetsV4::Color.black #=> {:red=>0.0, :green=>0.0, :blue=>0.0}
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run
-`rake spec` to run the tests. You can also run `bin/console` for an interactive
+After checking out the repo, run `bin/setup` to install dependencies and then, run
+`rake` to run the tests, static analysis, etc. 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
@@ -124,9 +362,6 @@ release a new version, update the version number in `version.rb`, and then run
 commits and the created tag, and push the `.gem` file to
 [rubygems.org](https://rubygems.org).
 
-## Creating a Google API Service Account
-
-
 ## Contributing
 
 Bug reports and pull requests are welcome on [the main-branch/sheets_v4 GitHub project](https://github.com/main-branch/sheets_v4).

data/examples/README.md

@@ -46,3 +46,4 @@
 * [ ] Protected ranges
 * [ ] Resize a sheet
 * [ ] Retrying on error
+* [ ] Set a custom datetime or decimal format for a range [1](https://developers.google.com/sheets/api/samples/formatting#set_a_custom_datetime_or_decimal_format_for_a_range)

data/lib/sheets_v4/{validate_api_objects → api_object_validation}/load_schemas.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module SheetsV4
-  module ValidateApiObjects
+  module ApiObjectValidation
     # Load the Google Discovery API description for the Sheets V4 API
     #
     # @example
     #   logger = Logger.new(STDOUT, :level => Logger::ERROR)
-    #   schemas = SheetsV4::ValidateApiObjects::LoadSchemas.new(logger:).call
+    #   schemas = SheetsV4::ApiObjectValidation::LoadSchemas.new(logger:).call
     #
     # @api private
     #
@@ -18,7 +18,7 @@ module SheetsV4
       # The schemas are only loaded once and cached.
       #
       # @example
-      #   schema_loader = SheetsV4::ValidateApiObjects::LoadSchemas.new
+      #   schema_loader = SheetsV4::ApiObjectValidation::LoadSchemas.new
       #
       # @param logger [Logger] the logger to use
       #
@@ -30,8 +30,8 @@ module SheetsV4
       #
       # @example
       #   logger = Logger.new(STDOUT, :level => Logger::INFO)
-      #   validator = SheetsV4::ValidateApiObjects::LoadSchemas.new(logger)
-      #   validator.logger == logger # => true
+      #   schema_loader = SheetsV4::ApiObjectValidation::LoadSchemas.new(logger)
+      #   schema_loader.logger == logger # => true
       #
       # @return [Logger]
       #
@@ -84,7 +84,7 @@ module SheetsV4
       # Log an error and raise a RuntimeError based on the HTTP response code
       # @param http_response [Net::HTTPResponse] the HTTP response
       # @return [void]
-      # @raises [RuntimeError]
+      # @raise [RuntimeError]
       # @api private
       def raise_error(http_response)
         message = "HTTP Error '#{http_response.code}' loading schemas from '#{http_response.uri}'"
@@ -146,7 +146,7 @@ module SheetsV4
       # @return [void]
       # @api private
       def post_process_schemas(schemas)
-        SheetsV4::ValidateApiObjects::TraverseObjectTree.call(
+        SheetsV4::ApiObjectValidation::TraverseObjectTree.call(
           object: schemas, visitor: ->(path:, object:) { schema_visitor(path:, object:) }
         )
       end

data/lib/sheets_v4/{validate_api_objects → api_object_validation}/resolve_schema_ref.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module SheetsV4
-  module ValidateApiObjects
+  module ApiObjectValidation
     # Resolve a JSON schema reference to a Google Sheets API schema
     #
     # This class uses the Google Discovery API to get the schemas. Any schema reference
@@ -9,14 +9,14 @@ module SheetsV4
     # name in the Google Discovery API and returning the schema object (as a Hash).
     #
     # This means that `{ "$ref": "cell_data" }` is resolved by returning
-    # `SheetsV4::ValidateApiObjects::LoadSchemas.new(logger:).call['cell_data']`.
+    # `SheetsV4::ApiObjectValidation::LoadSchemas.new(logger:).call['cell_data']`.
     #
-    # An RuntimeError is raised if `SheetsV4::ValidateApiObjects::LoadSchemas.new.call`
+    # An RuntimeError is raised if `SheetsV4::ApiObjectValidation::LoadSchemas.new.call`
     # does not have a key matching the schema name.
     #
     # @example
     #   logger = Logger.new(STDOUT, level: Logger::INFO)
-    #   ref_resolver = SheetsV4::ValidateApiObjects::ResolveSchemaRef.new(logger:)
+    #   ref_resolver = SheetsV4::ApiObjectValidation::ResolveSchemaRef.new(logger:)
     #   people_schema = { 'type' => 'array', 'items' => { '$ref' => 'person' } }
     #   json_validator = JSONSchemer.schema(people_schema, ref_resolver:)
     #   people_json = [{ 'name' => { 'first' => 'John', 'last' => 'Doe' } }]
@@ -53,7 +53,7 @@ module SheetsV4
 
       # Resolve a JSON schema reference
       #
-      # @param ref [URI] the reference to resolve usually in the form "json-schemer://schema/{name}"
+      # @param ref [URI] the reference to resolve usually in the form "json-schemer://schema/[name]"
       #
       # @return [Hash] the schema object as a hash
       #
@@ -62,7 +62,7 @@ module SheetsV4
       def call(ref)
         schema_name = ref.path[1..]
         logger.debug { "Reading schema #{schema_name}" }
-        schemas = SheetsV4::ValidateApiObjects::LoadSchemas.new(logger:).call
+        schemas = SheetsV4::ApiObjectValidation::LoadSchemas.new(logger:).call
         schemas[schema_name].tap do |schema_object|
           raise "Schema for #{ref} not found" unless schema_object
         end

data/lib/sheets_v4/{validate_api_objects → api_object_validation}/traverse_object_tree.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module SheetsV4
-  module ValidateApiObjects
+  module ApiObjectValidation
     # Visit all objects in arbitrarily nested object tree of hashes and/or arrays
     #
     # @api public
@@ -16,7 +16,7 @@ module SheetsV4
       #
       # ```Ruby
       # visitor = -> (path:, object:) { puts "path: #{path}, object: #{obj}" }
-      # SheetsV4::ValidateApiObjects::TraverseObjectTree.call(object:, visitor:)
+      # SheetsV4::ApiObjectValidation::TraverseObjectTree.call(object:, visitor:)
       # ```
       #
       # @example Given a simple object (not very exciting)

data/lib/sheets_v4/api_object_validation/validate_api_object.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/inflector'
+require 'json_schemer'
+
+module SheetsV4
+  module ApiObjectValidation
+    # Validate objects against a Google Sheets API request object schema
+    #
+    # @api public
+    #
+    class ValidateApiObject
+      # Create a new api object validator
+      #
+      # By default, a nil logger is used. This means that no messages are logged.
+      #
+      # @example
+      #   validator = SheetsV4::ApiObjectValidation::ValidateApiObject.new
+      #
+      # @param logger [Logger] the logger to use
+      #
+      def initialize(logger: Logger.new(nil))
+        @logger = logger
+      end
+
+      # The logger to use internally
+      #
+      # Validation errors are logged at the error level. Other messages are logged
+      # at the debug level.
+      #
+      # @example
+      #   logger = Logger.new(STDOUT, :level => Logger::INFO)
+      #   validator = SheetsV4::ApiObjectValidation::ValidateApiObject.new(logger)
+      #   validator.logger == logger # => true
+      #   validator.logger.debug { "Debug message" }
+      #
+      # @return [Logger]
+      #
+      attr_reader :logger
+
+      # Validate the object using the JSON schema named schema_name
+      #
+      # @example
+      #   schema_name = 'batch_update_spreadsheet_request'
+      #   object = { 'requests' => [] }
+      #   validator = SheetsV4::ApiObjectValidation::ValidateApiObject.new
+      #   validator.call(schema_name:, object:)
+      #
+      # @param schema_name [String] the name of the schema to validate against
+      # @param object [Object] the object to validate
+      #
+      # @raise [RuntimeError] if the object does not conform to the schema
+      #
+      # @return [void]
+      #
+      def call(schema_name:, object:)
+        logger.debug { "Validating #{object} against #{schema_name}" }
+
+        schema = { '$ref' => schema_name }
+        schemer = JSONSchemer.schema(schema, ref_resolver:)
+        errors = schemer.validate(object)
+        raise_error!(schema_name, object, errors) if errors.any?
+
+        logger.debug { "Object #{object} conforms to #{schema_name}" }
+      end
+
+      private
+
+      # The resolver to use to resolve JSON schema references
+      # @return [ResolveSchemaRef]
+      # @api private
+      def ref_resolver = @ref_resolver ||= SheetsV4::ApiObjectValidation::ResolveSchemaRef.new(logger:)
+
+      # Raise an error when the object does not conform to the schema
+      # @return [void]
+      # @raise [RuntimeError]
+      # @api private
+      def raise_error!(schema_name, object, errors)
+        error = errors.first['error']
+        error_message = "Object #{object} does not conform to #{schema_name}: #{error}"
+        logger.error(error_message)
+        raise error_message
+      end
+    end
+  end
+end

data/lib/sheets_v4/api_object_validation.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SheetsV4
+  # Validate API Objects against the Google Discovery API
+  #
+  # @example
+  #   logger = Logger.new(STDOUT, :level => Logger::ERROR)
+  #   schema_name = 'batch_update_spreadsheet_request'
+  #   object = { 'requests' => [] }
+  #   SheetsV4::ApiObjectValidation::ValidateApiObject.new(logger:).call(schema_name:, object:)
+  #
+  # @api public
+  #
+  module ApiObjectValidation; end
+end
+
+require_relative 'api_object_validation/load_schemas'
+require_relative 'api_object_validation/resolve_schema_ref'
+require_relative 'api_object_validation/traverse_object_tree'
+require_relative 'api_object_validation/validate_api_object'

data/lib/sheets_v4/color.rb

@@ -23,7 +23,6 @@ module SheetsV4
       #
       # @param method_name [#to_sym] the name of the color
       # @param arguments [Array] ignored
-      # @param block [Proc] ignored
       # @return [Hash] the color object
       # @api private
       def method_missing(method_name, *arguments, &)

data/lib/sheets_v4/convert_dates_and_times.rb

@@ -0,0 +1,243 @@
+# Copyright (c) 2023 Yahoo
+
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/values/time_zone'
+require 'active_support/core_ext/numeric/time'
+require 'active_support/core_ext/string/zones'
+
+module SheetsV4
+  # Convert between Ruby Date and DateTime objects and Google Sheets values
+  #
+  # Google Sheets uses decimal values to represent dates and times. These
+  # conversion routines allows converting from Ruby Date and DateTime objects
+  # and values that Google Sheets recognize.
+  #
+  # DateTime objects passed to `datetime_to_gs` or `date_to_gs` are converted to
+  # the time zone of the spreadsheet given in the initializer. DateTime objects
+  # returned by `gs_to_datetime` are always in the spreadsheet's time zone.
+  #
+  # Valid time zone names are those listed in one of these two sources:
+  # * `ActiveSupport::TimeZone.all.map { |tz| tz.tzinfo.name }`
+  # * `ActiveSupport::TimeZone.all.map(&:name)`
+  #
+  # @example
+  #   tz = spreadsheet.properties.time_zone #=> e.g. 'America/Los_Angeles'
+  #   converter = SheetsV4::ConvertDatesAndTimes.new(tz)
+  #   date = Date.parse('1967-03-15')
+  #   converter.date_to_gs(date) #=> 24546
+  #   converter.gs_to_date(24546) #=> #<Date: 1967-03-15 ((2439565j,0s,0n),+0s,2299161j)>
+  #
+  #   date_time = DateTime.parse('2021-05-17 11:36:00 UTC')
+  #   converter.datetime_to_gs(date_time) #=> 44333.191666666666
+  #   converter.gs_to_datetime(44333.191666666666)
+  #   #=> #<DateTime: 2021-05-17T11:36:00+00:00 ((2459352j,41760s,0n),+0s,2299161j)>
+  #
+  # @api public
+  #
+  class ConvertDatesAndTimes
+    # The time zone passed into the initializer
+    #
+    # @example
+    #   time_zone = 'UTC'
+    #   converter = SheetsV4::ConvertDatesAndTimes.new(time_zone)
+    #   converter.spreadsheet_tz
+    #   #=> #<ActiveSupport::TimeZone:0x00007fe39000f908 @name="America/Los_Angeles", ...>
+    #
+    # @return [ActiveSupport::TimeZone] the time zone
+    #
+    attr_reader :spreadsheet_tz
+
+    # Initialize the conversion routines for a spreadsheet
+    #
+    # @example
+    #   time_zone = 'America/Los_Angeles'
+    #   converter = SheetsV4::ConvertDatesAndTimes.new(time_zone)
+    #
+    # @param spreadsheet_tz [String] the time zone set in the spreadsheet properties
+    #
+    # @raise [RuntimeError] if the time zone is not valid
+    #
+    def initialize(spreadsheet_tz)
+      @spreadsheet_tz = ActiveSupport::TimeZone.new(spreadsheet_tz)
+      raise "Invalid time zone '#{spreadsheet_tz}'" unless @spreadsheet_tz
+    end
+
+    # Convert a Ruby DateTime object to a Google Sheets date time value
+    #
+    # @example
+    #   time_zone = 'America/Los_Angeles'
+    #   converter = SheetsV4::ConvertDatesAndTimes.new(time_zone)
+    #   date_time = DateTime.parse('2021-05-17 11:36:00 UTC')
+    #   converter.datetime_to_gs(date_time) #=> 44333.191666666666
+    #
+    # @param datetime [DateTime, nil] the date and time to convert
+    #
+    # @return [Float, String] the value to store in a Google Sheets cell
+    #   Returns a Float if datetime is not nil; otherwise, returns an empty string.
+    #
+    def datetime_to_gs(datetime)
+      return '' unless datetime
+
+      time = datetime.to_time.in_time_zone(spreadsheet_tz)
+      unix_to_gs_epoch(replace_time_zone(time, 'UTC').to_i)
+    end
+
+    # Convert a Google Sheets date time value to a DateTime object
+    #
+    # Time is rounded to the nearest second. The DateTime object returned is in
+    # the spreadsheet's time zone given in the initiaizer.
+    #
+    # @example
+    #   time_zone = 'America/Los_Angeles'
+    #   converter = SheetsV4::ConvertDatesAndTimes.new(time_zone)
+    #   gs_value = 44333.191666666666
+    #   converter.gs_to_datetime(gs_value) #=> #<DateTime: 2021-05-17T04:35:59-07:00 ...>
+    #
+    # @param gs_datetime [Float, "", nil] the value from the Google Sheets cell
+    #
+    # @return [DateTime, nil] the value represented by gs_datetime
+    #   Returns a DateTime object if a Float was given; otherwise, returns nil if an
+    #   empty string or nil was given.
+    #
+    def gs_to_datetime(gs_datetime)
+      return nil if gs_datetime.nil? || gs_datetime == ''
+
+      raise 'gs_datetime is a string' if gs_datetime.is_a?(String)
+
+      unix_epoch_datetime = gs_to_unix_epoch(gs_datetime.to_f)
+      time = Time.at_without_coercion(unix_epoch_datetime, in: 'UTC')
+      replace_time_zone(time, spreadsheet_tz).to_datetime
+    end
+
+    # Convert a Ruby Date object to a Google Sheets date value
+    #
+    # The Google Sheets date value is a float.
+    #
+    # @example with a Date object
+    #   time_zone = 'America/Los_Angeles'
+    #   converter = SheetsV4::ConvertDatesAndTimes.new(time_zone)
+    #   date = Date.parse('2021-05-17')
+    #   converter.date_to_gs(date) #=> 44333
+    #
+    # @example with a DateTime object
+    #   time_zone = 'America/Los_Angeles'
+    #   converter = SheetsV4::ConvertDatesAndTimes.new(time_zone)
+    #   date_time = DateTime.parse('2021-05-17 11:36:00 UTC')
+    #   converter.date_to_gs(date_time) #=> 44333
+    #
+    # @param date [DateTime, Date, nil] the date to convert
+    #
+    # @return [Float, String] the value to sstore in a Google Sheets cell
+    #   Returns a Float if date is not nil; otherwise, returns an empty string
+    #
+    def date_to_gs(date)
+      return datetime_to_gs(date).to_i if date.is_a?(DateTime)
+
+      return (date - gs_epoch_start_date).to_i if date.is_a?(Date)
+
+      ''
+    end
+
+    # Convert a Google Sheets date value to a Ruby Date object
+    #
+    # @example with a Date value
+    #   time_zone = 'America/Los_Angeles'
+    #   converter = SheetsV4::ConvertDatesAndTimes.new(time_zone)
+    #   gs_value = 44333
+    #   converter.gs_to_date(gs_value) #=> #<Date: 2021-05-17 ...>
+    #
+    # @example with a Date and Time value
+    #   time_zone = 'America/Los_Angeles'
+    #   converter = SheetsV4::ConvertDatesAndTimes.new(time_zone)
+    #   gs_value = 44333.191666666666
+    #   converter.gs_to_date(gs_value) #=> #<Date: 2021-05-17 ...>
+    #
+    # @param gs_date [Float, "", nil] the value from the Google Sheets cell
+    #
+    # @return [Date, nil] the value represented by gs_date
+    #   Returns a Date object if a Float was given; otherwise, returns nil if an
+    #   empty string or nil was given.
+    #
+    def gs_to_date(gs_date)
+      return nil if gs_date.nil? || gs_date == ''
+
+      raise 'gs_date is a string' if gs_date.is_a?(String)
+
+      (gs_epoch_start_date + gs_date.to_i)
+    end
+
+    private
+
+    # The Google Sheets epoch start Date to use when calculating dates
+    # @return [Date] the 'zero' Date
+    # @api private
+    def gs_epoch_start_date
+      @gs_epoch_start_date ||= Date.parse('1899-12-30')
+    end
+
+    # The number of seconds in a day
+    #
+    # @return [Integer] number of seconds in a day
+    #
+    SECONDS_PER_DAY = 86_400
+
+    # The number of seconds between the Google Sheets Epoch and Unix Epoch
+    #
+    # Effectively the number of seconds between 1899-12-30 00:00:00 UTC and
+    # 1970-01-01 00:00:00 UTC.
+    #
+    # @return [Integer] the number of seconds
+    #
+    SECONDS_BETWEEN_GS_AND_UNIX_EPOCHS = 25_569 * 86_400
+
+    # Convert a gs_datetime to unix time
+    #
+    # @param gs_datetime [Float] time relative to the Google Sheets Epoch
+    #
+    # gs_datetime is a float representing the number of days since the start of
+    # the Google Sheets epoch (1899-12-30 00:00:00 UTC).
+    #
+    # @return [Integer] the same datetime in Unix Time rounded to the nearest second
+    #
+    # Unix time is an integer representing the number of seconds since the start of
+    # the Unix Epoch (1970-01-01 00:00:00 UTC). The number returned is rounded
+    # to the nearest second.
+    #
+    # @api private
+    #
+    def gs_to_unix_epoch(gs_datetime)
+      (gs_datetime * SECONDS_PER_DAY).round - SECONDS_BETWEEN_GS_AND_UNIX_EPOCHS
+    end
+
+    # Convert a unix time to gs_datetime
+    #
+    # @param unix_time [Integer] seconds since the Unix epoch 1970-01-01 00:00:00 UTC
+    #
+    # @return [Float] days since the Google Sheets epoch 1899-12-30 00:00:00 UTC
+    #
+    # @api private
+    #
+    def unix_to_gs_epoch(unix_time)
+      (unix_time + SECONDS_BETWEEN_GS_AND_UNIX_EPOCHS).to_f / SECONDS_PER_DAY
+    end
+
+    # Given a time, change the time zone without impacting the displayed date/time
+    #
+    # @example
+    #   replace_time_zone(Time.parse('2021-05-21 11:40 UTC'), 'America/Los_Angeles')
+    #   #=> '2021-05-21 11:40 -0700'
+    #
+    # @param time [Time] the time object to adjust
+    # @param time_zone_name [String] the desired time zone
+    #
+    # @return [Time] the resulting time object
+    #
+    # @api private
+    #
+    def replace_time_zone(time, time_zone_name)
+      time.asctime.in_time_zone(time_zone_name)
+    end
+  end
+end

data/lib/sheets_v4/{credential_creator.rb → create_credential.rb}

@@ -5,7 +5,7 @@ require 'json_schemer'
 module SheetsV4
   # Creates a Google API credential with an access token
   #
-  class CredentialCreator
+  class CreateCredential
     # Creates a Google API credential with an access token
     #
     # This wraps the boiler plate code into one function to make constructing a
@@ -14,7 +14,7 @@ module SheetsV4
     # @example Constructing a credential from the contents of ~/.credential
     #   credential_source = File.read(File.join(Dir.home, '.credential'))
     #   scope = Google::Apis::SheetsV4::AUTH_SPREADSHEETS
-    #   credential = GoogleApisHelpers.credential(credential_source, scope)
+    #   credential = SheetsV4::CreateCredential.call(credential_source, scope)
     #
     # @param [Google::Auth::*, String, IO, nil] credential_source may be one of four things:
     #   (1) a previously created credential that you want to reuse, (2) a credential read

data/lib/sheets_v4/validate_api_objects/{validate.rb → validate_api_object.rb}

@@ -1,21 +1,22 @@
 # frozen_string_literal: true
 
+require 'active_support'
 require 'active_support/inflector'
 require 'json_schemer'
 
 module SheetsV4
-  module ValidateApiObjects
+  module ApiObjectValidation
     # Validate objects against a Google Sheets API request object schema
     #
     # @api public
     #
-    class Validate
+    class ValidateApiObject
       # Create a new validator
       #
       # By default, a nil logger is used. This means that no messages are logged.
       #
       # @example
-      #   validator = SheetsV4::ValidateApiObjects::Validator.new
+      #   validator = SheetsV4::ApiObjectValidation::ValidateApiObject.new
       #
       # @param logger [Logger] the logger to use
       #
@@ -30,7 +31,7 @@ module SheetsV4
       #
       # @example
       #   logger = Logger.new(STDOUT, :level => Logger::INFO)
-      #   validator = SheetsV4::ValidateApiObjects::Validator.new(logger)
+      #   validator = SheetsV4::ApiObjectValidation::ValidateApiObject.new(logger)
       #   validator.logger == logger # => true
       #   validator.logger.debug { "Debug message" }
       #
@@ -43,7 +44,7 @@ module SheetsV4
       # @example
       #   schema_name = 'batch_update_spreadsheet_request'
       #   object = { 'requests' => [] }
-      #   validator = SheetsV4::ValidateApiObjects::Validator.new
+      #   validator = SheetsV4::ApiObjectValidation::ValidateApiObject.new
       #   validator.call(schema_name:, object:)
       #
       # @param schema_name [String] the name of the schema to validate against
@@ -69,7 +70,7 @@ module SheetsV4
       # The resolver to use to resolve JSON schema references
       # @return [ResolveSchemaRef]
       # @api private
-      def ref_resolver = @ref_resolver ||= SheetsV4::ValidateApiObjects::ResolveSchemaRef.new(logger:)
+      def ref_resolver = @ref_resolver ||= SheetsV4::ApiObjectValidation::ResolveSchemaRef.new(logger:)
 
       # Raise an error when the object does not conform to the schema
       # @return [void]

data/lib/sheets_v4/validate_api_objects.rb

@@ -7,14 +7,14 @@ module SheetsV4
   #   logger = Logger.new(STDOUT, :level => Logger::ERROR)
   #   schema_name = 'batch_update_spreadsheet_request'
   #   object = { 'requests' => [] }
-  #   SheetsV4::ValidateApiObjects::Validator.new(logger:).call(schema_name:, object:)
+  #   SheetsV4::ApiObjectValidation::ValidateApiObject.new(logger:).call(schema_name:, object:)
   #
   # @api public
   #
-  module ValidateApiObjects; end
+  module ApiObjectValidation; end
 end
 
-require_relative 'validate_api_objects/load_schemas'
-require_relative 'validate_api_objects/resolve_schema_ref'
-require_relative 'validate_api_objects/traverse_object_tree'
-require_relative 'validate_api_objects/validate'
+require_relative 'api_object_validation/load_schemas'
+require_relative 'api_object_validation/resolve_schema_ref'
+require_relative 'api_object_validation/traverse_object_tree'
+require_relative 'api_object_validation/validate_api_object'

data/lib/sheets_v4/version.rb

@@ -2,5 +2,5 @@
 
 module SheetsV4
   # The version of this gem
-  VERSION = '0.5.0'
+  VERSION = '0.7.0'
 end

data/lib/sheets_v4.rb

@@ -2,9 +2,14 @@
 
 require_relative 'sheets_v4/version'
 require_relative 'sheets_v4/color'
-require_relative 'sheets_v4/credential_creator'
-require_relative 'sheets_v4/validate_api_objects'
+require_relative 'sheets_v4/convert_dates_and_times'
+require_relative 'sheets_v4/create_credential'
+require_relative 'sheets_v4/api_object_validation'
 
+require 'active_support'
+require 'active_support/values/time_zone'
+require 'active_support/core_ext/numeric/time'
+require 'active_support/core_ext/string/zones'
 require 'google/apis/sheets_v4'
 require 'json'
 require 'logger'
@@ -15,87 +20,221 @@ require 'net/http'
 # @api public
 #
 module SheetsV4
-  # Create a new Google::Apis::SheetsV4::SheetsService object
-  #
-  # Simplifies creating and configuring a the credential.
-  #
-  # @example using the crednetial in `~/.google-api-credential`
-  #   SheetsV4.sheets_service
-  #
-  # @example using a credential passed in as a string
-  #   credential_source = File.read(File.join(Dir.home, '.credential'))
-  #   SheetsV4.sheets_service(credential_source:
-  #
-  # @param credential_source [nil, String, IO, Google::Auth::*] may
-  #   be either an already constructed credential, the credential read into a String or
-  #   an open file with the credential ready to be read. Passing `nil` will result
-  #   in the credential being read from `~/.google-api-credential.json`.
-  #
-  # @param scopes [Object, Array] one or more scopes to access.
-  #
-  # @param credential_creator [#credential] Used to inject the credential creator for
-  #   testing.
-  #
-  # @return a new SheetsService instance
-  #
-  def self.sheets_service(credential_source: nil, scopes: nil, credential_creator: SheetsV4::CredentialCreator)
-    credential_source ||= File.read(File.expand_path('~/.google-api-credential.json'))
-    scopes ||= [Google::Apis::SheetsV4::AUTH_SPREADSHEETS]
-
-    Google::Apis::SheetsV4::SheetsService.new.tap do |service|
-      service.authorization = credential_creator.call(credential_source, scopes)
+  class << self
+    # Create a new Google::Apis::SheetsV4::SheetsService object
+    #
+    # Simplifies creating and configuring a the credential.
+    #
+    # @example using the credential in `~/.google-api-credential`
+    #   SheetsV4.sheets_service
+    #
+    # @example using a credential passed in as a string
+    #   credential_source = File.read(File.expand_path('~/.google-api-credential.json'))
+    #   SheetsV4.sheets_service(credential_source:)
+    #
+    # @example using a credential passed in as an IO
+    #   credential_source = File.open(File.expand_path('~/.google-api-credential.json'))
+    #   SheetsV4.sheets_service(credential_source:)
+    #
+    # @param credential_source [nil, String, IO, Google::Auth::*] may
+    #   be either an already constructed credential, the credential read into a String or
+    #   an open file with the credential ready to be read. Passing `nil` will result
+    #   in the credential being read from `~/.google-api-credential.json`.
+    #
+    # @param scopes [Object, Array] one or more scopes to access.
+    #
+    # @param credential_creator [#credential] Used to inject the credential creator for
+    #   testing.
+    #
+    # @return a new SheetsService instance
+    #
+    def sheets_service(credential_source: nil, scopes: nil, credential_creator: SheetsV4::CreateCredential)
+      credential_source ||= File.read(File.expand_path('~/.google-api-credential.json'))
+      scopes ||= [Google::Apis::SheetsV4::AUTH_SPREADSHEETS]
+
+      Google::Apis::SheetsV4::SheetsService.new.tap do |service|
+        service.authorization = credential_creator.call(credential_source, scopes)
+      end
     end
-  end
 
-  # Validate the object using the named JSON schema
-  #
-  # The JSON schemas are loaded from the Google Disocvery API. The schemas names are
-  # returned by `SheetsV4.api_object_schemas.keys`.
-  #
-  # @example
-  #   schema_name = 'BatchUpdateSpreadsheetRequest'
-  #   object = { 'requests' => [] }
-  #   SheetsV4.validate_api_object(schema_name:, object:)
-  #
-  # @param schema_name [String] the name of the schema to validate against
-  # @param object [Object] the object to validate
-  # @param logger [Logger] the logger to use for logging error, info, and debug message
-  #
-  # @raise [RuntimeError] if the object does not conform to the schema
-  #
-  # @return [void]
-  #
-  def self.validate_api_object(schema_name:, object:, logger: Logger.new(nil))
-    SheetsV4::ValidateApiObjects::Validate.new(logger:).call(schema_name:, object:)
-  end
+    # Validate the object using the named JSON schema
+    #
+    # The JSON schemas are loaded from the Google Disocvery API. The schemas names are
+    # returned by `SheetsV4.api_object_schema_names`.
+    #
+    # @example
+    #   schema_name = 'batch_update_spreadsheet_request'
+    #   object = { 'requests' => [] }
+    #   SheetsV4.validate_api_object(schema_name:, object:)
+    #
+    # @param schema_name [String] the name of the schema to validate against
+    # @param object [Object] the object to validate
+    # @param logger [Logger] the logger to use for logging error, info, and debug message
+    #
+    # @raise [RuntimeError] if the object does not conform to the schema
+    #
+    # @return [void]
+    #
+    def validate_api_object(schema_name:, object:, logger: Logger.new(nil))
+      SheetsV4::ApiObjectValidation::ValidateApiObject.new(logger:).call(schema_name:, object:)
+    end
 
-  # Given the name of the color, return a Google Sheets API color object
-  #
-  # Available color names are listed using `SheetsV4.color_names`.
-  #
-  # The object returned is frozen.  If you want a color you can change (for instance,
-  # to adjust the `alpha` attribute), you must clone the object returned.
-  #
-  # @example
-  #   SheetsV4::Color.color(:red) #=> { "red": 1.0, "green": 0.0, "blue": 0.0 }
-  #
-  # @param name [#to_sym] the name of the color requested
-  #
-  # @return [Hash] The color requested e.g. `{ "red": 1.0, "green": 0.0, "blue": 0.0 }`
-  #
-  # @api public
-  #
-  def self.color(name)
-    SheetsV4::Color::COLORS[name.to_sym] || raise("Color #{name} not found")
-  end
+    # List the names of the schemas available to use in the Google Sheets API
+    #
+    # @example List the name of the schemas available
+    #   SheetsV4.api_object_schema_names #=> ["add_banding_request", "add_banding_response", ...]
+    #
+    # @return [Array<String>] the names of the schemas available
+    #
+    def api_object_schema_names(logger: Logger.new(nil))
+      SheetsV4::ApiObjectValidation::LoadSchemas.new(logger:).call.keys.sort
+    end
+
+    # Given the name of the color, return a Google Sheets API color object
+    #
+    # Available color names are listed using `SheetsV4.color_names`.
+    #
+    # The object returned is frozen.  If you want a color you can change (for instance,
+    # to adjust the `alpha` attribute), you must clone the object returned.
+    #
+    # @example
+    #   SheetsV4::Color.color(:red) #=> { "red": 1.0, "green": 0.0, "blue": 0.0 }
+    #
+    # @param name [#to_sym] the name of the color requested
+    #
+    # @return [Hash] The color requested e.g. `{ "red": 1.0, "green": 0.0, "blue": 0.0 }`
+    #
+    def color(name)
+      SheetsV4::Color::COLORS[name.to_sym] || raise("Color #{name} not found")
+    end
+
+    # List the names of the colors available to use in the Google Sheets API
+    #
+    # @example
+    #   SheetsV4::Color.color_names #=> [:black, :white, :red, :green, :blue, :yellow, :magenta, :cyan, ...]
+    #
+    # @return [Array<Symbol>] the names of the colors available
+    #
+    def color_names = SheetsV4::Color::COLORS.keys
+
+    # @!attribute [rw] default_spreadsheet_tz
+    #
+    # Set the default time zone for date and time conversions
+    #
+    # Valid time zone names are those listed in one of these two sources:
+    # * `ActiveSupport::TimeZone.all.map { |tz| tz.tzinfo.name }`
+    # * `ActiveSupport::TimeZone.all.map(&:name)`
+    #
+    # If you want to set the timezone to the time zone of the system's local time,
+    # you could use the [timezone_local gem](https://rubygems.org/gems/timezone_local).
+    #
+    # @example
+    #   SheetsV4.default_spreadsheet_tz = 'America/Los_Angeles'
+    #
+    # @example Set the time zone to the system's local time
+    #   require 'timezone_local'
+    #   SheetsV4.default_spreadsheet_tz = TimeZone::Local.get.name
+    #
+    # @return [void]
+    #
+    def default_spreadsheet_tz
+      @default_spreadsheet_tz || raise('default_spreadsheet_tz not set')
+    end
+
+    def default_spreadsheet_tz=(time_zone)
+      raise "Invalid time zone '#{time_zone}'" unless ActiveSupport::TimeZone.new(time_zone)
 
-  # List the names of the colors available to use in the Google Sheets API
-  #
-  # @example
-  #   SheetsV4::Color.color_names #=> [:black, :white, :red, :green, :blue, :yellow, :magenta, :cyan, ...]
-  #
-  # @return [Array<Symbol>] the names of the colors available
-  # @api public
-  #
-  def self.color_names = SheetsV4::Color::COLORS.keys
+      @default_date_and_time_converter = nil unless @default_spreadsheet_tz == time_zone
+      @default_spreadsheet_tz = time_zone
+    end
+
+    # The default converter for dates and times
+    # @return [SheetsV4::ConvertDatesAndTimes]
+    # @api private
+    def default_date_and_time_converter
+      @default_date_and_time_converter ||= SheetsV4::ConvertDatesAndTimes.new(default_spreadsheet_tz)
+    end
+
+    # Convert a Ruby Date object to a Google Sheet date value
+    #
+    # Uses the time zone given by `SheetsV4.default_spreadsheet_tz`.
+    #
+    # @example with a Date object
+    #   SheetsV4.default_spreadsheet_tz = 'America/Los_Angeles'
+    #   date = Date.parse('2021-05-17')
+    #   SheetsV4.date_to_gs(date) #=> 44333
+    #
+    # @example with a DateTime object
+    #   SheetsV4.default_spreadsheet_tz = 'America/Los_Angeles'
+    #   date_time = DateTime.parse('2021-05-17 11:36:00 UTC')
+    #   SheetsV4.date_to_gs(date_time) #=> 44333
+    #
+    # @param date [DateTime, Date, nil] the date to convert
+    #
+    # @return [Float, String] the value to sstore in a Google Sheet cell
+    #   Returns a Float if date is not nil; otherwise, returns an empty string
+    #
+    def date_to_gs(date)
+      default_date_and_time_converter.date_to_gs(date)
+    end
+
+    # Convert a Google Sheets date value to a Ruby Date object
+    #
+    # @example with a date value
+    #   SheetsV4.default_spreadsheet_tz = 'America/Los_Angeles'
+    #   gs_value = 44333
+    #   SheetsV4.gs_to_date(gs_value) #=> #<Date: 2021-05-17 ...>
+    #
+    # @example with a date and time value
+    #   SheetsV4.default_spreadsheet_tz = 'America/Los_Angeles'
+    #   gs_value = 44333.191666666666
+    #   SheetsV4.gs_to_date(gs_value) #=> #<Date: 2021-05-17 ...>
+    #
+    # @param gs_value [Float, "", nil] the value from the Google Sheets cell
+    #
+    # @return [Date, nil] the value represented by gs_date
+    #
+    #   Returns a Date object if a Float was given; otherwise, returns nil if an
+    #   empty string or nil was given.
+    #
+    def gs_to_date(gs_value)
+      default_date_and_time_converter.gs_to_date(gs_value)
+    end
+
+    # Convert a Ruby DateTime object to a Google Sheets value
+    #
+    # @example
+    #   SheetsV4.default_spreadsheet_tz = 'America/Los_Angeles'
+    #   date_time = DateTime.parse('2021-05-17 11:36:00 UTC')
+    #   SheetsV4.datetime_to_gs(date_time) #=> 44333.191666666666
+    #
+    # @param datetime [DateTime, nil] the date and time to convert
+    #
+    # @return [Float, String] the value to store in a Google Sheet cell
+    #   Returns a Float if datetime is not nil; otherwise, returns an empty string.
+    #
+    def datetime_to_gs(datetime)
+      default_date_and_time_converter.datetime_to_gs(datetime)
+    end
+
+    # Convert a Google Sheets date time value to a DateTime object
+    #
+    # Time is rounded to the nearest second. The DateTime object returned is in
+    # the time zone given by `SheetsV4.default_spreadsheet_tz`.
+    #
+    # @example
+    #   SheetsV4.default_spreadsheet_tz = 'America/Los_Angeles'
+    #   gs_value = 44333.191666666666
+    #   SheetsV4.gs_to_datetime(gs_value) #=> #<DateTime: 2021-05-17T04:35:59-07:00 ...>
+    #
+    # @param gs_value [Float, "", nil] the value from the Google Sheets cell
+    #
+    # @return [DateTime, nil] the value represented by gs_datetime
+    #   Returns a DateTime object if a Float was given; otherwise, returns nil if an
+    #   empty string or nil was given.
+    #
+    def gs_to_datetime(gs_value)
+      default_date_and_time_converter.gs_to_datetime(gs_value)
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sheets_v4
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - James Couball
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-02 00:00:00.000000000 Z
+date: 2023-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler-audit
@@ -260,13 +260,16 @@ files:
 - examples/set_background_color
 - examples/set_background_color2
 - lib/sheets_v4.rb
+- lib/sheets_v4/api_object_validation.rb
+- lib/sheets_v4/api_object_validation/load_schemas.rb
+- lib/sheets_v4/api_object_validation/resolve_schema_ref.rb
+- lib/sheets_v4/api_object_validation/traverse_object_tree.rb
+- lib/sheets_v4/api_object_validation/validate_api_object.rb
 - lib/sheets_v4/color.rb
-- lib/sheets_v4/credential_creator.rb
+- lib/sheets_v4/convert_dates_and_times.rb
+- lib/sheets_v4/create_credential.rb
 - lib/sheets_v4/validate_api_objects.rb
-- lib/sheets_v4/validate_api_objects/load_schemas.rb
-- lib/sheets_v4/validate_api_objects/resolve_schema_ref.rb
-- lib/sheets_v4/validate_api_objects/traverse_object_tree.rb
-- lib/sheets_v4/validate_api_objects/validate.rb
+- lib/sheets_v4/validate_api_objects/validate_api_object.rb
 - lib/sheets_v4/version.rb
 homepage: https://github.com/main-branch/sheets_v4
 licenses: