squake 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbe25ba449a2b7838a20ae80a5bcd9106bfe21a2f2626185a9eb901dc9e2f58a
-  data.tar.gz: 18b8e92dabac3f0f0657a27b6adadd9616530421c640c4b6a584f1d454e16596
+  metadata.gz: f7838d5d10515e9d94811494249d36e789e441a04ab31f7e94c83c306a9fb2bf
+  data.tar.gz: 61d6f7415ec816567ebf260493d43f1a3515090b9062e1740b339f4eb40de405
 SHA512:
-  metadata.gz: b302c402858193ee25d25ed3ed610362b1bb00ce477956c9c6f7e440b312e758b9eddd6861841f5fb8059eb0300728d85707b44964d2f10614a4f20429c3bf4c
-  data.tar.gz: ee363ceeb88006801dfcc7a6be2535ac82357e001cd3e71c6b4d86e722f71719b84fcc536897cb1505374cd7a2226f17764ddc2e7bff678c0cef62ac234473ae
+  metadata.gz: 314d29865f690a9d4f7faf867269686dc5b184e9e36aa988d5ea19c60b75d608e09d9e90ccd086f733cfb01dd753c8c8b036a406cb48f1d3444d61f57b049fdc
+  data.tar.gz: 1234e584e92277e455c8d3094b3624e54e37b972af10c27c1f6836ce5bb4ca54f92f2b548fe95be5dca2531b6c9d7f0a87072aae1fb0afd4e5f06be163287394

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2023-06-21
+
+### Added
+
+* added `Squake.configure`
+* introduced global config allowig to omit the `client` from all service calls
+
+### Changed
+
+* All public services now return a `Return` class that contains the actual data or an error object. This replaces the throwing of errors for control-flow.
+
+## [0.2.1 - 0.2.4] - 2023-06-21
+
+### Fixed
+
+* Boilerplate bugs
+
 ## [0.2.0] - 2023-06-15
 
 ### Added

data/README.md

@@ -2,6 +2,8 @@
 
 Find the documentation here: [docs](https://docs.squake.earth/).
 
+This gem follows SemVer, however only after a stable release 1.0.0 is made.
+
 ## Installation
 
 Via rubygems:
@@ -10,10 +12,10 @@ Via rubygems:
 gem 'squake'
 ```
 
-Via git:
+Test the latest version via git:
 
 ```ruby
-gem 'squake', git: 'git@github.com:squake-earth/squake-ruby'
+gem 'squake', git: 'git@github.com:squake-earth/squake-ruby', branch: :main
 ```
 
 ## Auth
@@ -30,7 +32,9 @@ You need a different API Key for production and sandbox.
 
 ## Usage
 
-Initialize the client:
+### Initialize the client
+
+either explicitly anywhere in the app
 
 ```ruby
 config = Squake::Config.new(
@@ -46,9 +50,34 @@ config = Squake::Config.new(
 client = Squake::Client.new(config: config)
 ```
 
-Calculate emissions
+or once globally in e.g. an initializer
+
+```ruby
+Squake.configure do |config|
+  config.api_key = ENV.fetch('SQUAKE_API_KEY') # optional if ENV var `SQUAKE_API_KEY` is set
+  config.sandbox_mode = true                   # set to `false` for production
+  config.keep_alive_timeout = 30               # optional, default: 30
+  config.logger = Logger.new($stdout)          # Set this to `Rails.logger` when using Rails
+  config.enforced_api_base = nil               # for testing to e.g. point to a local server
+end
+```
+
+If you have the API Key in an ENV var named `SQUAKE_API_KEY`, you don't need any further config.
+
+### Fetch available products
+
+```ruby
+context = Squake::Products.get
+products = context.result # [Squake::Model::Product]
+```
+
+### Define items you want emissions to be computed
+
+Find all available item types and methodologies in the [docs](https://docs-v2.squake.earth/group/endpoint-calculations).
 
 ```ruby
+# NOTE: some items are also available as typed objects, found at `lib/squake/model/items/**/*.rb`
+#       where `.../items/private_jet/squake` is the item for type "private_jet" and methodology "squake".
 items = [
   {
     type: 'flight',
@@ -59,69 +88,81 @@ items = [
     number_of_travellers: 2,
     aircraft_type: '350',
     external_reference: 'booking-id',
-  }
+  },
+  Squake::Model::Items::PrivateJet::Squake.new(
+    origin: 'SIN',
+    destination: 'HND',
+    external_reference: 'my-booking-id',
+    identifier: 'P180',
+    identifier_kind: 'ICAO',
+  ),
 ]
+```
+
+### Calculate emissions (without price quote)
 
-# returns Squake::Model::Carbon
-carbon = Squake::Calculation.create(
-  client: client,        # required
+```ruby
+context = Squake::Calculation.create(
   items: items,          # required
   carbon_unit: 'gram',   # optional, default: 'gram', other options: 'kilogram', 'tonne'
   expand: [],            # optional, default: [], allowed values: 'items' to enrich the response
+  client: client,        # optional
 )
+
+# alias: context.failed?
+if context.success?
+  context.result # Squake::Model::Carbon
+else
+  context.errors # [Squake::Errors::APIErrorResult]
+end
 ```
 
-Calculate emissions and include a price quote:
+### Calculate emissions and include a price quote
 
 ```ruby
-# Find all available item types and methodologies here:
-#   https://docs-v2.squake.earth/group/endpoint-calculations
-items = [
-  {
-    type: 'flight',
-    methodology: 'ICAO',
-    origin: 'BER',
-    destination: 'SIN',
-    booking_class: 'economy',
-    number_of_travellers: 2,
-    aircraft_type: '350',
-    external_reference: 'booking-id',
-  }
-]
-
-# returns Squake::Model::Pricing
-pricing = Squake::CalculationWithPricing.quote(
-  client: client,        # required
+context = Squake::CalculationWithPricing.quote(
   items: items,          # required
   product: 'product-id', # required
   currency: 'EUR',       # optional, default: 'EUR'
   carbon_unit: 'gram',   # optional, default: 'gram', other options: 'kilogram', 'tonne'
   expand: [],            # optional, default: [], allowed values: 'items', 'product', 'price' to enrich the response
+  client: client,        # optional
 )
+
+if context.success?
+  context.result # Squake::Model::Pricing
+else
+  context.errors # [Squake::Errors::APIErrorResult]
+end
 ```
 
-Place a purchase order; by default the library injects a `SecureRandom.uuid` as `external_reference` to ensure idempotency, i.e. you can safely retry the request if it fails.
+### Place a purchase order
+
+by default the library injects a `SecureRandom.uuid` as `external_reference` to ensure idempotency, i.e. you can safely retry the request if it fails.
 
 ```ruby
 uuid = SecureRandom.uuid
 
 # returns Squake::Model::Purchase
-purchase = Squake::Purchase.create(
-  client: client,           # required
+context = Squake::Purchase.create(
   pricing: pricing.id,      # required, from above
   external_reference: uuid, # optional, default: SecureRandom.uuid, used for idempotency, if given, MUST be unique
+  client: client,           # optional
 )
 
+context.result # Squake::Model::Purchase
+context.errors # [Squake::Errors::APIErrorResult]
+
 # retrieve the purchase later
 Squake::Purchase.retrieve(
-  client: client,  # required
   id: purchase.id, # required
+  client: client,  # optional
 )
 
 # within 14 days, you can cancel the purchase worry-free
 Squake::Purchase.cancel(
-  client: client,  # required
   id: purchase.id, # required
+  client: client,  # optional
 )
 ```
 
@@ -133,22 +174,10 @@ Please commit small and focused PRs with descriptive commit messages. If you are
 
 ## Publishing a new version
 
-Have a Rubygems API key in your `~/.gem/credentials` file.
-
-```shell
----
-:rubygems_squake: rubygems_xxx
-```
-
-Then run:
+run
 
 ```shell
 bin/release
 ```
 
-which will guide you through the release process:
-
-* create a new git tag from current main
-* create a GitHub release from the tag
-* build the gem locally
-* publish the gem to RubyGems
+which will guide you through the release process.

data/lib/squake/calculation.rb

@@ -10,13 +10,13 @@ module Squake
 
     sig do
       params(
-        client: Squake::Client,
         items: T::Array[T.any(Squake::Model::Items::BaseType, T::Hash[T.any(String, Symbol), T.untyped])],
         carbon_unit: String,
         expand: T::Array[String],
-      ).returns(Squake::Model::Carbon)
+        client: Squake::Client,
+      ).returns(Squake::Return[Squake::Model::Carbon])
     end
-    def self.create(client:, items:, carbon_unit: 'gram', expand: [])
+    def self.create(items:, carbon_unit: 'gram', expand: [], client: Squake::Client.new)
       # @TODO: add typed objects for all possible items. Until then, we allow either a Hash or a T::Struct
       items = items.map do |item|
         item.is_a?(T::Struct) ? item.serialize : item
@@ -26,16 +26,24 @@ module Squake
         path: ENDPOINT,
         method: :post,
         params: {
-          items: items.map(&:serialize),
+          items: items,
           carbon_unit: carbon_unit,
           expand: expand,
         },
       )
-      raise Squake::APIError.new(response: result) unless result.success?
 
-      Squake::Model::Carbon.from_api_response(
-        T.cast(result.body, T::Hash[Symbol, T.untyped]),
-      )
+      if result.success?
+        carbon = Squake::Model::Carbon.from_api_response(
+          T.cast(result.body, T::Hash[Symbol, T.untyped]),
+        )
+        Return.new(result: carbon)
+      else
+        error = Squake::Errors::APIErrorResult.new(
+          code: :"api_error_#{result.code}",
+          detail: result.error_message,
+        )
+        Return.new(errors: [error])
+      end
     end
   end
 end

data/lib/squake/calculation_with_pricing.rb

@@ -10,15 +10,15 @@ module Squake
 
     sig do
       params(
-        client: Squake::Client,
         items: T::Array[T.any(Squake::Model::Items::BaseType, T::Hash[T.any(String, Symbol), T.untyped])],
         product: String,
         currency: String,
         carbon_unit: String,
         expand: T::Array[String],
-      ).returns(Squake::Model::Pricing)
+        client: Squake::Client,
+      ).returns(Squake::Return[Squake::Model::Pricing])
     end
-    def self.quote(client:, items:, product:, currency: 'EUR', carbon_unit: 'gram', expand: [])
+    def self.quote(items:, product:, currency: 'EUR', carbon_unit: 'gram', expand: [], client: Squake::Client.new)
       # @TODO: add typed objects for all possible items. Until then, we allow either a Hash or a T::Struct
       items = items.map do |item|
         item.is_a?(T::Struct) ? item.serialize : item
@@ -35,11 +35,19 @@ module Squake
           expand: expand,
         },
       )
-      raise Squake::APIError.new(response: result) unless result.success?
 
-      Squake::Model::Pricing.from_api_response(
-        T.cast(result.body, T::Hash[Symbol, T.untyped]),
-      )
+      if result.success?
+        pricing = Squake::Model::Pricing.from_api_response(
+          T.cast(result.body, T::Hash[Symbol, T.untyped]),
+        )
+        Return.new(result: pricing)
+      else
+        error = Squake::Errors::APIErrorResult.new(
+          code: :"api_error_#{result.code}",
+          detail: result.error_message,
+        )
+        Return.new(errors: [error])
+      end
     end
   end
 end

data/lib/squake/client.rb

@@ -14,9 +14,9 @@ module Squake
       )
     end
 
-    sig { params(config: Squake::Config).void }
-    def initialize(config:)
-      @config = config
+    sig { params(config: T.nilable(Squake::Config)).void }
+    def initialize(config: nil)
+      @config = T.let(config || T.must(Squake.configuration), Squake::Config)
     end
 
     sig do
@@ -53,7 +53,7 @@ module Squake
     end
     private def execute_request(method:, path:, headers: {}, params: nil, api_base: nil, api_key: nil)
       api_base ||= @config.api_base
-      api_key ||= @config.api_key
+      api_key ||= T.must(@config.api_key)
 
       body_params = nil
       query_params = nil

data/lib/squake/config.rb

@@ -10,11 +10,11 @@ module Squake
     DEFAULT_BASE_URL = T.let('https://api.squake.earth', String)
     SANDBOX_BASE_URL = T.let('https://api.sandbox.squake.earth', String)
 
-    const :api_key, String
-    const :keep_alive_timeout, Integer, default: 30
-    const :logger, ::Logger, factory: -> { ::Logger.new($stdout) }
-    const :sandbox_mode, T::Boolean, default: true
-    const :enforced_api_base, T.nilable(String)
+    prop :api_key, T.nilable(String)
+    prop :keep_alive_timeout, Integer, default: 30
+    prop :logger, ::Logger, factory: -> { ::Logger.new($stdout) }
+    prop :sandbox_mode, T::Boolean, default: true
+    prop :enforced_api_base, T.nilable(String)
 
     sig { returns(String) }
     def api_base

data/lib/squake/errors/api_error_result.rb

@@ -0,0 +1,22 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'api_error_source'
+
+module Squake
+  module Errors
+    #
+    # https://jsonapi.org/format/#errors
+    #
+    # > Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document.
+    #
+    class APIErrorResult < T::Struct
+      const :code, Symbol # An application-specific error code
+
+      # A human-readable explanation specific to this occurrence of the problem.
+      # Like title, this field's value can be localized.
+      const :detail, T.nilable(String)
+      const :source, T.nilable(APIErrorSource)
+    end
+  end
+end

data/lib/squake/errors/api_error_source.rb

@@ -0,0 +1,12 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Squake
+  module Errors
+    class APIErrorSource < T::Struct
+      const :attribute, T.any(Symbol, String)
+      const :model, T.nilable(String), default: nil
+      const :id, T.nilable(String), default: nil # external reference if given
+    end
+  end
+end

data/lib/squake/model/carbon.rb

@@ -15,8 +15,8 @@ module Squake
       sig { params(response_body: T::Hash[Symbol, T.untyped]).returns(Squake::Model::Carbon) }
       def self.from_api_response(response_body)
         Squake::Model::Carbon.new(
-          quantity: BigDecimal(String(response_body.fetch(:quantity))),
-          unit: CarbonUnit.deserialize(response_body.fetch(:unit)),
+          quantity: BigDecimal(String(response_body.fetch(:carbon_quantity))),
+          unit: CarbonUnit.deserialize(response_body.fetch(:carbon_unit)),
           items: response_body.fetch(:items, nil),
         )
       end

data/lib/squake/model/price.rb

@@ -9,21 +9,19 @@ module Squake
       const :id, String
       const :product, String
       const :unit_amount, BigDecimal
-      const :valid_from, T.nilable(Date)
+      const :valid_from, Date
       const :carbon_unit, String
       const :currency, String
 
       sig { params(response_body: T::Hash[Symbol, T.untyped]).returns(Squake::Model::Price) }
       def self.from_api_response(response_body)
-        product = response_body.fetch(:price, {})
-
         Squake::Model::Price.new(
-          id: product.fetch(:id),
-          product: product.fetch(:product),
-          unit_amount: product.fetch(:unit_amount).to_d,
-          valid_from: Date.parse(product.fetch(:valid_from, nil)),
-          carbon_unit: product.fetch(:carbon_unit),
-          currency: product.fetch(:currency),
+          id: response_body.fetch(:id),
+          product: response_body.fetch(:product),
+          unit_amount: BigDecimal(response_body.fetch(:unit_amount).to_s),
+          valid_from: Date.parse(response_body.fetch(:valid_from)),
+          carbon_unit: response_body.fetch(:carbon_unit),
+          currency: response_body.fetch(:currency),
         )
       end
     end

data/lib/squake/model/pricing.rb

@@ -24,8 +24,8 @@ module Squake
       const :carbon_quantity, BigDecimal
       const :carbon_unit, String
       const :payment_link, T.nilable(String)
-      const :price, Squake::Model::Price
-      const :product, Squake::Model::Product
+      const :price, T.any(Squake::Model::Price, String)
+      const :product, T.any(Squake::Model::Product, String)
       const :valid_until, Date
       const :currency, String, default: 'EUR'
       const :total, Integer
@@ -33,10 +33,13 @@ module Squake
 
       sig { params(response_body: T::Hash[Symbol, T.untyped]).returns(Squake::Model::Pricing) }
       def self.from_api_response(response_body)
-        price = Squake::Model::Price.from_api_response(response_body)
-        product = Squake::Model::Product.from_api_response(response_body)
+        price_or_id = T.let(response_body.fetch(:price), T.any(String, T::Hash[Symbol, T.untyped]))
+        price = price_or_id.is_a?(Hash) ? Squake::Model::Price.from_api_response(price_or_id) : price_or_id
 
-        items = response_body.fetch(:items, [])
+        product_or_id = T.let(response_body.fetch(:product), T.any(String, T::Hash[Symbol, T.untyped]))
+        product = product_or_id.is_a?(Hash) ? Squake::Model::Product.from_api_response(product_or_id) : product_or_id
+
+        items = response_body.fetch(:items, []) || []
         items.map! do |item|
           item[:carbon_quantity] = item.fetch(:carbon_quantity).to_d
           item[:distance] = item.fetch(:distance).to_d

data/lib/squake/model/product.rb

@@ -8,14 +8,14 @@ module Squake
 
       const :id, String
       const :title, String
+      const :certifications, T::Array[String], default: []
 
       sig { params(response_body: T::Hash[Symbol, T.untyped]).returns(Squake::Model::Product) }
       def self.from_api_response(response_body)
-        product = response_body.fetch(:product, {})
-
         Squake::Model::Product.new(
-          id: product.fetch(:id),
-          title: product.fetch(:title),
+          id: response_body.fetch(:id),
+          title: response_body.fetch(:title),
+          certifications: response_body.fetch(:certifications, []),
         )
       end
     end

data/lib/squake/products.rb

@@ -11,12 +11,12 @@ module Squake
 
     sig do
       params(
-        client: Squake::Client,
-        locale: String,
         product_id: T.nilable(String),
-      ).returns(T::Array[Squake::Model::Product])
+        locale: String,
+        client: Squake::Client,
+      ).returns(Squake::Return[T::Array[Squake::Model::Product]])
     end
-    def self.get(client:, locale: DEFAULT_LOCALE, product_id: nil)
+    def self.get(product_id: nil, locale: DEFAULT_LOCALE, client: Squake::Client.new)
       path = product_id.nil? ? ENDPOINT : "#{ENDPOINT}/#{product_id}"
 
       result = client.call(
@@ -26,10 +26,18 @@ module Squake
           locale: locale,
         },
       )
-      raise Squake::APIError.new(response: result) unless result.success?
 
-      Array(result.body).map do |product_data|
-        Squake::Model::Product.from_api_response({ product: product_data })
+      if result.success?
+        products = T.cast(Array(result.body), T::Array[T::Hash[Symbol, T.untyped]]).map do |product_data|
+          Squake::Model::Product.from_api_response(product_data)
+        end
+        Return.new(result: products)
+      else
+        error = Squake::Errors::APIErrorResult.new(
+          code: :"api_error_#{result.code}",
+          detail: result.error_message,
+        )
+        Return.new(errors: [error])
       end
     end
   end

data/lib/squake/purchase.rb

@@ -11,16 +11,16 @@ module Squake
     # rubocop:disable Metrics/ParameterLists,  Layout/LineLength
     sig do
       params(
-        client: Squake::Client,
         pricing: String,
         confirmation_document: T.nilable(T::Hash[Symbol, T.untyped]),
         certificate_document: T.nilable(T::Hash[Symbol, T.untyped]),
         metadata: T.nilable(T::Hash[Symbol, T.untyped]),
         external_reference: String, # used for idempotency, if given, MUST be unique
         expand: T::Array[String],
-      ).returns(Squake::Model::Purchase)
+        client: Squake::Client,
+      ).returns(Squake::Return[Squake::Model::Purchase])
     end
-    def self.create(client:, pricing:, confirmation_document: nil, certificate_document: nil, metadata: nil, external_reference: SecureRandom.uuid, expand: [])
+    def self.create(pricing:, confirmation_document: nil, certificate_document: nil, metadata: nil, external_reference: SecureRandom.uuid, expand: [], client: Squake::Client.new)
       result = client.call(
         path: ENDPOINT,
         method: :post,
@@ -33,48 +33,73 @@ module Squake
           expand: expand,
         },
       )
-      raise Squake::APIError.new(response: result) unless result.success?
 
-      Squake::Model::Purchase.from_api_response(
-        T.cast(result.body, T::Hash[Symbol, T.untyped]),
-      )
+      if result.success?
+        purchase = Squake::Model::Purchase.from_api_response(
+          T.cast(result.body, T::Hash[Symbol, T.untyped]),
+        )
+        Return.new(result: purchase)
+      else
+        error = Squake::Errors::APIErrorResult.new(
+          code: :"api_error_#{result.code}",
+          detail: result.error_message,
+        )
+        Return.new(errors: [error])
+      end
     end
     # rubocop:enable Metrics/ParameterLists,  Layout/LineLength
 
     sig do
       params(
-        client: Squake::Client,
         id: String,
-      ).returns(T.nilable(Squake::Model::Purchase))
+        client: Squake::Client,
+      ).returns(T.nilable(Squake::Return[Squake::Model::Purchase]))
     end
-    def self.retrieve(client:, id:)
+    def self.retrieve(id:, client: Squake::Client.new)
       result = client.call(
         path: "#{ENDPOINT}/#{id}",
       )
       return nil if result.code == 404
-      raise Squake::APIError.new(response: result) unless result.success?
 
-      Squake::Model::Purchase.from_api_response(
-        T.cast(result.body, T::Hash[Symbol, T.untyped]),
-      )
+      if result.success?
+        purchase = Squake::Model::Purchase.from_api_response(
+          T.cast(result.body, T::Hash[Symbol, T.untyped]),
+        )
+        Return.new(result: purchase)
+      else
+        error = Squake::Errors::APIErrorResult.new(
+          code: :"api_error_#{result.code}",
+          detail: result.error_message,
+        )
+        Return.new(errors: [error])
+      end
     end
 
     sig do
       params(
-        client: Squake::Client,
         id: String,
-      ).returns(T.nilable(Squake::Model::Purchase))
+        client: Squake::Client,
+      ).returns(T.nilable(Squake::Return[Squake::Model::Purchase]))
     end
-    def self.cancel(client:, id:)
+    def self.cancel(id:, client: Squake::Client.new)
       result = client.call(
         path: "#{ENDPOINT}/#{id}/cancel",
         method: :post,
       )
-      raise Squake::APIError.new(response: result) unless result.success?
+      return nil if result.code == 404
 
-      Squake::Model::Purchase.from_api_response(
-        T.cast(result.body, T::Hash[Symbol, T.untyped]),
-      )
+      if result.success?
+        purchase = Squake::Model::Purchase.from_api_response(
+          T.cast(result.body, T::Hash[Symbol, T.untyped]),
+        )
+        Return.new(result: purchase)
+      else
+        error = Squake::Errors::APIErrorResult.new(
+          code: :"api_error_#{result.code}",
+          detail: result.error_message,
+        )
+        Return.new(errors: [error])
+      end
     end
   end
 end

data/lib/squake/return.rb

@@ -0,0 +1,64 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'errors/api_error_result'
+
+module Squake
+  class Return
+    class Failure < StandardError; end
+
+    FAILURE_MSG_NO_ARGS = 'Must provide either a result or errors'
+    FAILURE_MSG_BOTH_ARGS = 'Cannot provide both a result and errors'
+    FAILURE_ERRORS_CALLED_WHEN_SUCCESS = 'Cannot call errors when result is present'
+
+    extend T::Sig
+    extend T::Generic
+
+    Error = type_member { { fixed: Errors::APIErrorResult } }
+    Result = type_member { { upper: Object } }
+
+    sig { params(result: T.nilable(Result), errors: T.nilable(T::Array[Error])).void }
+    def initialize(result: nil, errors: nil)
+      raise Failure, FAILURE_MSG_NO_ARGS if result.nil? && errors.nil?
+      raise Failure, FAILURE_MSG_BOTH_ARGS if present?(result) && present?(errors)
+
+      @result = result
+      @errors = errors
+    end
+
+    sig { returns(T::Boolean) }
+    def success?
+      present?(@result)
+    end
+
+    sig { returns(T::Boolean) }
+    def failed?
+      !success?
+    end
+
+    sig { returns(T::Array[Error]) }
+    def errors
+      raise Failure, FAILURE_ERRORS_CALLED_WHEN_SUCCESS if success?
+
+      T.must(@errors)
+    end
+
+    sig { returns(Result) }
+    def result
+      raise Failure, @errors&.map(&:serialize) if failed?
+
+      T.must(@result)
+    end
+
+    # courtesy to Rails, see: https://api.rubyonrails.org/v7.0.5/classes/Object.html
+    sig { params(object: T.untyped).returns(T::Boolean) }
+    private def blank?(object)
+      object.respond_to?(:empty?) ? !!object.empty? : !object
+    end
+
+    sig { params(object: T.untyped).returns(T::Boolean) }
+    private def present?(object)
+      !blank?(object)
+    end
+  end
+end

data/lib/squake/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Squake
-  VERSION = '0.2.4'
+  VERSION = '0.3.0'
 end

data/lib/squake.rb

@@ -5,11 +5,36 @@ require 'sorbet-runtime'
 require 'oj'
 require 'net/http'
 
-Dir[File.join(__dir__, './**/*', '*.rb')].each { require(_1) }
-
-module Squake; end
-
 Oj.default_options = {
   mode: :compat, # required to dump hashes with symbol-keys
   symbol_keys: true,
 }
+
+Dir[File.join(__dir__, './**/*', '*.rb')].each { require(_1) }
+
+module Squake
+  class << self
+    extend T::Sig
+
+    sig { returns(T.nilable(Squake::Config)) }
+    attr_accessor :configuration
+
+    sig do
+      params(
+        _: T.proc.params(configuration: Squake::Config).void,
+      ).void
+    end
+    def configure(&_)
+      self.configuration ||= Squake::Config.new(
+        api_key: ENV.fetch('SQUAKE_API_KEY', nil),
+        keep_alive_timeout: ENV.fetch('SQUAKE_KEEP_ALIVE_TIMEOUT', 30).to_i,
+        sandbox_mode: ENV.fetch('SQUAKE_SANDBOX_MODE', 'true').casecmp?('true'),
+        enforced_api_base: ENV.fetch('SQUAKE_API_BASE', nil),
+      )
+
+      yield(T.must(configuration))
+    end
+  end
+end
+
+Squake.configure(&:itself) unless ENV['SQUAKE_API_KEY'].nil?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: squake
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - SQUAKE
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-15 00:00:00.000000000 Z
+date: 2023-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http
@@ -138,6 +138,8 @@ files:
 - lib/squake/calculation_with_pricing.rb
 - lib/squake/client.rb
 - lib/squake/config.rb
+- lib/squake/errors/api_error_result.rb
+- lib/squake/errors/api_error_source.rb
 - lib/squake/model/carbon.rb
 - lib/squake/model/carbon_unit.rb
 - lib/squake/model/items/base_type.rb
@@ -149,6 +151,7 @@ files:
 - lib/squake/products.rb
 - lib/squake/purchase.rb
 - lib/squake/response.rb
+- lib/squake/return.rb
 - lib/squake/util.rb
 - lib/squake/version.rb
 - sorbet/rbi/dsl/active_support/callbacks.rbi