yield-sdk 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af8b2c1dec3366d6eeb12c8fc24e583bae64b1268b511b4c920e654e3b9a95df
-  data.tar.gz: 388ab9535c4a2147654b26c0b4f52f51adf2d00f7c545d67bbb36db1c8b2d5d6
+  metadata.gz: edf5ef23bf25b6d5b424ce3f6e9d0a3a40b045176901bf2de01078b86d34cce6
+  data.tar.gz: 8fa6343f723d3f4051f15b5e606e887775f819f0889438e6866fca59bdbb4e58
 SHA512:
-  metadata.gz: 6e693cd40f47786c4e2d974069ae1ac129ee1df334a7983b339f8b587082f6b6e569cf830b9d64da8b1a5de9eda4018cf1823bdb5c6ff1365e53a5e4109ef792
-  data.tar.gz: 7d116dd36ce3fbe42be6a01f883bf810110f148a55ba7fd9e80b7fe5640c74a205ff9efaa0dc16eb39f7c425b3a27808f9c3cf0a1b13416400514b810c245cec
+  metadata.gz: 74d0b5a43f40bd586ebc345c7b8590c48bfd97d4c684236868516260f626efe78f25c73b2f21bf7ab6f152d5dc83f2fae7ad2e44b8d17f1ac5ea36d8df3daf19
+  data.tar.gz: 300efc9e709e883246445d924e004517408ab263e122b1cf46384e74228cca88623a23c5b92ea5adb2f973c36de97ffd0949b1ad65be9ad6919ae8d2b21a74b2

data/.rubocop.yml

@@ -0,0 +1,51 @@
+plugins:
+  - rubocop-minitest
+  - rubocop-rake
+
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+
+Gemspec/RequireMFA:
+  Enabled: false # FIXME
+
+Style/AccessorGrouping:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/MultipleComparison:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/TrailingCommaInArguments:
+  Enabled: true
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInArrayLiteral:
+  Enabled: true
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: true
+  EnforcedStyleForMultiline: comma
+
+Layout/LineLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false

data/README.md

@@ -1,27 +1,42 @@
-# The official Yield SDK for Ruby
+Yield SDK for Ruby [![Gem Version](https://img.shields.io/gem/v/yield-sdk)](https://rubygems.org/gems/yield-sdk)
+==================
 
-## Installation
+The official [Yield](https://www.paywithyield.com) SDK for Ruby.
+
+
+Documentation
+-------------
+
+- [API reference](https://github.com/yield-tech/sdk-ruby/blob/main/docs/index.md)
+
+
+Installation
+------------
 
 ```sh
 gem install yield-sdk
 ```
 
-## Usage
+
+Usage
+-----
 
 ```ruby
 require "yield/sdk"
 
-# for security, never commit the actual key in your code
-client = Yield::SDK::Client.new(ENV["YIELD_API_KEY"])
+# For security, don't save the actual key in your code or repo
+client = Yield::SDK::Client.new(ENV.fetch("YIELD_API_KEY"))
 
-# fetch an existing order
+# Fetch an existing order
 order = client.order.fetch("ord_...")
 p order.customer.registered_name
 
-# or create a new one
+# Or create a new one
 new_order = client.order.create({
-    customer_id: "org_...",
-    total_amount: "PHP 1234.50",
-    note: "Test order from the Ruby SDK!"
+  customer_id: "org_...",
+  total_amount: "PHP 1234.50",
+  note: "Test order from the Ruby SDK!"
 })
 ```
+
+For more details, check out our [API reference](https://github.com/yield-tech/sdk-ruby/blob/main/docs/index.md).

data/Rakefile

@@ -9,6 +9,15 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/test_*.rb"]
 end
 
-require "standard/rake"
+require "rubocop/rake_task"
 
-task default: %i[test standard]
+RuboCop::RakeTask.new
+
+require "steep/rake_task"
+
+Steep::RakeTask.new do |t|
+  t.check.severity_level = :error
+  t.watch.verbose
+end
+
+task default: %i[test rubocop steep]

data/Steepfile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+D = Steep::Diagnostic
+
+target :lib do
+  signature "sig"
+
+  check "lib"
+  # ignore "lib/.../*.rb"
+
+  library "base64"
+  library "bigdecimal"
+  library "date"
+  library "json"
+  library "openssl"
+  library "time"
+  library "uri"
+
+  configure_code_diagnostics(D::Ruby.strict)
+end

data/docs/index.md

@@ -0,0 +1,12 @@
+API Reference
+=============
+
+**Contents:**
+- General overview (TBD)
+- Error handling (TBD)
+- Types (TBD)
+- Pagination (TBD)
+- Modules
+    - [Customer module](./modules/customer.md)
+    - [Order module](./modules/order.md)
+    - [Self module](./modules/self.md)

data/docs/modules/customer.md

@@ -0,0 +1,64 @@
+[*← Return to index*](../index.md)
+
+Customer module
+===============
+
+**Endpoints:**
+- ![query](https://img.shields.io/badge/QUERY-green) [`list(params)`](#-listparams)
+
+**Objects:**
+- [`CustomerRow`](#customerrow)
+- [`CustomerCreditLineInfo`](#customercreditlineinfo)
+
+
+Endpoints
+---------
+
+### ![query](https://img.shields.io/badge/QUERY-green) `list(params)`
+
+Provides the list of customers under your account, ordered by creation time (newest first).
+
+```ruby
+params = { field: value, ... }
+customers = client.customer.list(params)
+
+# or pass them as keyword arguments
+customers = client.customer.list(field: value, ...)
+
+# or since the parameters are all optional
+customers = client.customer.list
+```
+
+**Returns:** `Page` of [`CustomerRow`](#customerrow)
+
+**Parameters:**
+
+- `params`: `Hash` — See the fields right below.
+
+| Field           | Required? | Type         | Description                                             |
+| --------------- | --------- | ------------ | ------------------------------------------------------- |
+| `limit`         | Optional  | `Integer`    | The maximum number of results to return. Default: `10`. |
+| `after`         | Optional  | `CursorLike` | See docs on pagination.                                 |
+| `customer_code` | Optional  | `String`     | Filter by customer code.                                |
+
+
+Objects
+-------
+
+### `CustomerRow`
+
+| Field             | Type                                                         | Description                                   |
+| ----------------- | ------------------------------------------------------------ | --------------------------------------------- |
+| `id`              | `String`                                                     | The ID of the customer.                       |
+| `registered_name` | `String`                                                     | The official registered name of the customer. |
+| `trade_name`      | `String` \| `nil`                                            | The trade name of the customer.               |
+| `customer_code`   | `String` \| `nil`                                            | The customer code assigned to this customer.  |
+| `credit_line`     | [`CustomerCreditLineInfo`](#customercreditlineinfo) \| `nil` | The credit line of the customer.              |
+
+
+### `CustomerCreditLineInfo`
+
+| Field              | Type    | Description                                |
+| ------------------ | ------- | ------------------------------------------ |
+| `credit_limit`     | `Money` | The credit limit.                          |
+| `amount_available` | `Money` | The amount available for this credit line. |

data/docs/modules/order.md

@@ -0,0 +1,93 @@
+[*← Return to index*](../index.md)
+
+Order module
+============
+
+**Endpoints:**
+- ![query](https://img.shields.io/badge/QUERY-green) [`fetch(id)`](#-fetchid)
+- ![command](https://img.shields.io/badge/COMMAND-orange) [`create(params)`](#-createparams)
+
+**Objects:**
+- [`Order`](#order)
+- [`OrderStatus`](#orderstatus)
+- [`OrderCustomerInfo`](#ordercustomerinfo)
+
+
+Endpoints
+---------
+
+### ![query](https://img.shields.io/badge/QUERY-green) `fetch(id)`
+
+Provides information about the order specified.
+
+```ruby
+order = client.order.fetch(id)
+```
+
+**Returns:** [Order](#order)
+
+**Parameters:**
+
+- `id`: `String` — The ID of the order.
+
+
+### ![command](https://img.shields.io/badge/COMMAND-orange) `create(params)`
+
+Creates a new order.
+
+```ruby
+params = { field: value, ... }
+order = client.order.create(params)
+```
+
+**Returns:** [`Order`](#order) — The newly created order.
+
+**Parameters:**
+
+- `params`: `Hash` — See the fields right below.
+
+| Field          | Required? | Type        | Description                                                                    |
+| -------------- | --------- | ----------- | ------------------------------------------------------------------------------ |
+| `customer_id`  | Required* | `String`    | The (Yield) customer ID that this order will belong to.                        |
+| `total_amount` | Required  | `MoneyLike` | The total amount of the order.                                                 |
+| `note`         | Required* | `String`    | A note shown to the customer during checkout, such as details about the order. |
+
+\* These fields may become optional in a future release.
+
+
+Objects
+-------
+
+### `Order`
+
+| Field           | Type                                               | Description                                                                                   |
+| --------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `id`            | `String`                                           | The ID of the order.                                                                          |
+| `order_number`  | `String`                                           | The order number.                                                                             |
+| `status`        | [`OrderStatus`](#orderstatus)                      | The status of the order.                                                                      |
+| `customer`      | [`OrderCustomerInfo`](#ordercustomerinfo) \| `nil` | The customer this order belongs to.                                                           |
+| `date`          | `Date`                                             | The date of the order.                                                                        |
+| `total_amount`  | `Money`                                            | The total amount of the order.                                                                |
+| `note`          | `String` \| `nil`                                  | A note shown to the customer during checkout, such as details about the order.                |
+| `payment_link`  | `String` \| `nil`                                  | The payment link for the customer to confirm this order. May be `nil` if no longer available. |
+| `creation_time` | `Time`                                             | The timestamp when this order was created.                                                    |
+
+
+### `OrderStatus`
+
+| Value        | Description                                                                             |
+| ------------ | --------------------------------------------------------------------------------------- |
+| `:pending`   | The initial status for newly created orders. The customer has yet to confirm the order. |
+| `:confirmed` | The customer has confirmed the order.                                                   |
+| `:fulfilled` | The order has been marked as fulfilled.                                                 |
+| `:cancelled` | The order has been cancelled.                                                           |
+
+
+### `OrderCustomerInfo`
+
+| Field             | Type              | Description                                   |
+| ----------------- | ----------------- | --------------------------------------------- |
+| `id`              | `String`          | The ID of the customer.                       |
+| `registered_name` | `String`          | The official registered name of the customer. |
+| `trade_name`      | `String` \| `nil` | The trade name of the customer.               |
+| `customer_code`   | `String` \| `nil` | The customer code assigned to this customer.  |

data/docs/modules/self.md

@@ -0,0 +1,48 @@
+[*← Return to index*](../index.md)
+
+Self module
+===========
+
+**Endpoints:**
+- ![query](https://img.shields.io/badge/QUERY-green) [`info`](#-info)
+
+**Objects:**
+- [`SelfInfo`](#selfinfo)
+- [`SelfOrganizationInfo`](#selforganizationinfo)
+
+
+Endpoints
+---------
+
+### ![query](https://img.shields.io/badge/QUERY-green) `info`
+
+Provides information about the API key used to call this endpoint.
+
+```ruby
+info = client.self.info
+```
+
+**Returns:** [`SelfInfo`](#selfinfo)
+
+**Parameters:** None
+
+
+Objects
+-------
+
+### `SelfInfo`
+
+| Field          | Type                                            | Description                           |
+| -------------- | ----------------------------------------------- | ------------------------------------- |
+| `id`           | `String`                                        | The ID of the API key.                |
+| `name`         | `String`                                        | Name of the API key.                  |
+| `organization` | [`SelfOrganizationInfo`](#selforganizationinfo) | The organization this key belongs to. |
+
+
+### `SelfOrganizationInfo`
+
+| Field             | Type              | Description                                       |
+| ----------------- | ----------------- | ------------------------------------------------- |
+| `id`              | `String`          | The ID of the organization.                       |
+| `registered_name` | `String`          | The official registered name of the organization. |
+| `trade_name`      | `String` \| `nil` | The trade name of the organization.               |

data/lib/yield/sdk/api/api_client.rb

@@ -7,6 +7,7 @@ require "openssl"
 require "time"
 require "uri"
 
+require_relative "../utils/type_utils"
 require_relative "../version"
 require_relative "api_result"
 
@@ -14,47 +15,74 @@ module Yield
   module SDK
     module API
       class Client
+        def initialize(api_key, base_url: nil, conn: nil)
+          @base_url = base_url || "https://integrate.withyield.com/api/v1"
+          @api_key_token, @api_key_hmac_key = Client.extract_api_key(api_key)
+          @conn = conn || Faraday.new
+          @client_version = SDK.client_version
+        end
+
+        def self.extract_api_key(key)
+          # "$" is the old separator, supported for backwards compatibility
+          key_parts = key.gsub("$", ":").split(":")
+          raise ArgumentError, "Invalid Yield API key" if key_parts.length != 3
+
+          token = "#{key_parts[0]}$#{key_parts[1]}"
+          hmac_key = Base64.urlsafe_decode64(key_parts[2])
+          [token, hmac_key]
+        end
+
+        def self.build_signature(hmac_key, timestamp, path, body = nil)
+          parts = body.nil? ? [timestamp, path] : [timestamp, path, body]
+          message = parts.join("\n")
+          sig_bytes = OpenSSL::HMAC.digest("sha512", hmac_key, message)
+          Base64.urlsafe_encode64(sig_bytes, padding: false)
+        end
+
         def self.process_response(response, &from_payload_block)
           status_code = response.status
           request_id = response["X-Request-Id"]
 
-          if !response.success?
+          unless response.success?
             error_type = "unexpected_error"
-            body = nil
+            error_body = nil
 
             begin
               body = JSON.parse(response.body)
-              error_type = body["error"] if body["error"].is_a?(String)
-            rescue
+              if body.is_a?(Hash)
+                error_type = body["error"] if body["error"].is_a?(String)
+                error_body = body
+              end
+            rescue StandardError
               # ignore
             end
 
-            return Result.failure(status_code, request_id, error_type)
+            return Result.failure(status_code, request_id, error_type, error_body, nil)
           end
 
           begin
-            data = from_payload_block.call(JSON.parse(response.body, symbolize_names: true))
-          rescue
-            return Result.failure(status_code, request_id, "unexpected_payload")
+            body = JSON.parse(response.body, symbolize_names: true)
+            payload = TypeUtils.expect_record(body)
+            data = from_payload_block.call(payload)
+          rescue StandardError => e
+            return Result.failure(status_code, request_id, "invalid_response", nil, e)
           end
 
           Result.success(status_code, request_id, data)
         end
 
-        def initialize(api_key, base_url: nil, faraday_conn: nil)
-          @base_url = base_url || "https://integrate.withyield.com/api/v1"
-
-          key_parts = api_key.split("$")
-          raise ArgumentError, "Invalid Yield API key" if key_parts.length != 3
-          @api_key_token = "#{key_parts[0]}$#{key_parts[1]}"
-          @api_key_hmac_key = Base64.urlsafe_decode64(key_parts[2])
-
-          @faraday_conn = faraday_conn || Faraday.new
-          @client_version = SDK.client_version
-        end
-
         def run_query(path, params = nil)
-          full_path = params.nil? ? path : "#{path}?#{URI.encode_www_form(params)}"
+          full_path = path
+          unless params.nil?
+            # Faraday sorts query parameters by default,
+            # so we need to sort it as well for the signature to match.
+            # We can disable this globally, but that may be undesirable for some users.
+            # See: https://lostisland.github.io/faraday/#/customization/index?id=order-of-parameters
+            params = params.compact.to_a.sort_by! { |k, _v| k }
+            query_string = URI.encode_www_form(params)
+            full_path += "?#{query_string}" unless query_string.empty?
+          end
+
           call_endpoint(:get, full_path, nil)
         end
 
@@ -62,30 +90,19 @@ module Yield
           call_endpoint(:post, path, payload)
         end
 
-        def build_signature(path, body = nil, now = Time.now)
-          timestamp = now.utc.iso8601
-
-          parts = body.nil? ? [timestamp, path] : [timestamp, path, body]
-          message = parts.join("\n")
-
-          signature_bytes = OpenSSL::HMAC.digest("sha512", @api_key_hmac_key, message)
-          signature_b64 = Base64.urlsafe_encode64(signature_bytes, padding: false)
-
-          "#{@api_key_token}$#{timestamp}$#{signature_b64}"
-        end
-
         private
 
         def call_endpoint(method, path, payload)
-          headers = {"X-Yield-Client" => @client_version}
+          headers = { "X-Yield-Client" => @client_version }
 
           body = payload&.to_json
           headers["Content-Type"] = "application/json" if body
 
-          signature = build_signature(path, body)
-          headers["Authorization"] = "Yield-Sig #{signature}"
+          timestamp = Time.now.utc.iso8601
+          signature = Client.build_signature(@api_key_hmac_key, timestamp, path, body)
+          headers["Authorization"] = "Yield-Sig #{@api_key_token}$#{timestamp}$#{signature}"
 
-          @faraday_conn.run_request(method, @base_url + path, body, headers)
+          @conn.run_request(method, @base_url + path, body, headers)
         end
       end
     end

data/lib/yield/sdk/api/api_error.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Yield
+  module SDK
+    module API
+      class Error < StandardError
+        attr_reader :status_code
+        attr_reader :request_id
+        attr_reader :details
+
+        def initialize(status_code, request_id, error)
+          @status_code = status_code
+          @request_id = request_id
+          @details = error
+
+          error_info = error.type
+          if error.type == "validation_error" && !error.body.nil?
+            issues = JSON.generate(error.body["issues"])
+            error_info = "#{error_info} #{issues}"
+          end
+
+          unless error.exception.nil?
+            message = JSON.generate(error.exception.message)
+            error_info = "#{error_info} #{message}"
+          end
+
+          extra_info = [
+            "status_code=#{status_code}",
+            "request_id=#{request_id || "<none>"}",
+          ].join("; ")
+
+          super("Yield API error: #{error_info} [#{extra_info}]")
+        end
+      end
+    end
+  end
+end

data/lib/yield/sdk/api/api_error_details.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Yield
+  module SDK
+    module API
+      ErrorDetails = Data.define(:type, :body, :exception)
+    end
+  end
+end

data/lib/yield/sdk/api/api_result.rb

@@ -1,24 +1,41 @@
 # frozen_string_literal: true
 
+require_relative "api_error"
+require_relative "api_error_details"
+
 module Yield
   module SDK
     module API
-      class Result < Data.define(:status_code, :request_id, :data, :error)
+      class Result
+        attr_reader :status_code
+        attr_reader :request_id
+        attr_reader :error
+
+        def initialize(status_code:, request_id:, data:, error:)
+          @status_code = status_code
+          @request_id = request_id
+          @data = data
+          @error = error
+        end
+
         def ok?
           error.nil?
         end
 
         def data
-          raise Error, "Yield API error: #{error} [status_code=#{status_code}]" unless ok?
-          super
+          raise Error.new(status_code, request_id, error), cause: error.exception unless error.nil?
+
+          @data
         end
 
         def self.success(status_code, request_id, data)
-          new(status_code:, request_id:, data:, error: nil)
+          new(status_code: status_code, request_id: request_id, data: data, error: nil)
         end
 
-        def self.failure(status_code, request_id, error)
-          new(status_code:, request_id:, data: nil, error:)
+        def self.failure(status_code, request_id, error_type, error_body, exception)
+          error = ErrorDetails.new(error_type, error_body, exception)
+
+          new(status_code: status_code, request_id: request_id, data: nil, error: error)
         end
       end
     end

data/lib/yield/sdk/base_client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "api/api_client"
+require_relative "modules/customer/customer_base_client"
 require_relative "modules/order/order_base_client"
 require_relative "modules/self/self_base_client"
 
@@ -9,14 +10,16 @@ module Yield
     class BaseClient
       attr_reader :api
 
+      attr_reader :customer
       attr_reader :self
       attr_reader :order
 
-      def initialize(api_key, base_url: nil, faraday_conn: nil)
-        @api = API::Client.new(api_key, base_url:, faraday_conn:)
+      def initialize(api_key, base_url: nil, conn: nil)
+        @api = API::Client.new(api_key, base_url: base_url, conn: conn)
 
-        @self = Self::BaseClient.new(@api)
+        @customer = Customer::BaseClient.new(@api)
         @order = Order::BaseClient.new(@api)
+        @self = Self::BaseClient.new(@api)
       end
     end
   end

data/lib/yield/sdk/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "base_client"
+require_relative "modules/customer/customer_client"
 require_relative "modules/order/order_client"
 require_relative "modules/self/self_client"
 
@@ -9,14 +10,16 @@ module Yield
     class Client
       attr_reader :base
 
-      attr_reader :self
+      attr_reader :customer
       attr_reader :order
+      attr_reader :self
 
-      def initialize(api_key, base_url: nil, faraday_conn: nil)
-        @base = BaseClient.new(api_key, base_url:, faraday_conn:)
+      def initialize(api_key, base_url: nil, conn: nil)
+        @base = BaseClient.new(api_key, base_url: base_url, conn: conn)
 
-        @self = Self::Client.new(@base.self)
+        @customer = Customer::Client.new(@base.customer)
         @order = Order::Client.new(@base.order)
+        @self = Self::Client.new(@base.self)
       end
     end
   end