test-test-sink-test-test 0.0.2.pre.alpha.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b0b3135f8e32ef8791093777d9a9bd263cc2ebeae00c1720ede5f137b49619e1
+  data.tar.gz: d0e5de4d073038141ab8c9340ff81c582b021a645dbe5a544145d5d08e2c88a6
+SHA512:
+  metadata.gz: ab5b68f79778de0967482cad9b1025353f9dac4fa0f750b5355c90296249b3eaad465c3994eae926a2a8e4750b0551ec496954ddd855ebe6482fee9f18317c0b
+  data.tar.gz: 12865e7a6723f2df54e89c011e2b5cd35a671939795d5b39d91d4e8b63d3e33b43d2c31b3bedaf6464e63e0cc42807c604a4072697870519d3a70b560a804312

data/README.md

@@ -0,0 +1,151 @@
+# Sink Ruby API library
+
+The Sink Ruby library provides convenient access to the Sink REST API from any Ruby 3.0+
+application.
+
+It is generated with [Stainless](https://www.stainlessapi.com/).
+
+## Documentation
+
+Documentation for the most recent version of this gem can be found [on RubyDoc](https://rubydoc.info/github/stainless-sdks/sink-ruby-public).
+
+The underlying REST API documentation can be found on [stainlessapi.com](https://stainlessapi.com).
+
+## Installation
+
+To use this gem during the beta, install directly from GitHub with Bundler by
+adding the following to your application's `Gemfile`:
+
+```ruby
+gem "sink", git: "https://github.com/stainless-sdks/sink-ruby-public", branch: "main"
+```
+
+To fetch an initial copy of the gem:
+
+```sh
+bundle install
+```
+
+To update the version used by your application when updates are pushed to
+GitHub:
+
+```sh
+bundle update sink
+```
+
+## Usage
+
+```ruby
+require "sink"
+
+sink = Sink::Client.new(
+  user_token: "My User Token", # defaults to ENV["SINK_CUSTOM_API_KEY_ENV"]
+  environment: "sandbox", # defaults to "production"
+  username: "Robert",
+  some_number_arg_required_no_default: 0,
+  some_number_arg_required_no_default_no_env: 0,
+  required_arg_no_env: "<example>"
+)
+
+card = sink.cards.create(
+  type: "SINGLE_USE",
+  exp_month: "08",
+  not_: "TEST",
+  shipping_address: {
+    "address1" => "180 Varick St",
+    "city" => "New York",
+    "country" => "USA",
+    "first_name" => "Jason",
+    "last_name" => "Mimosa",
+    "state" => "NY",
+    "postal_code" => "H0H0H0"
+  }
+)
+
+puts(card.token)
+```
+
+### Errors
+
+When the library is unable to connect to the API, or if the API returns a
+non-success status code (i.e., 4xx or 5xx response), a subclass of
+`Sink::HTTP::Error` will be thrown:
+
+```ruby
+begin
+  sink.cards.create(type: "an_incorrect_type")
+rescue Sink::HTTP::Error => e
+  puts(e.code) # 400
+end
+```
+
+Error codes are as followed:
+
+| Cause            | Error Type                 |
+| ---------------- | -------------------------- |
+| HTTP 400         | `BadRequestError`          |
+| HTTP 401         | `AuthenticationError`      |
+| HTTP 403         | `PermissionDeniedError`    |
+| HTTP 404         | `NotFoundError`            |
+| HTTP 409         | `ConflictError`            |
+| HTTP 422         | `UnprocessableEntityError` |
+| HTTP 429         | `RateLimitError`           |
+| HTTP >=500       | `InternalServerError`      |
+| Other HTTP error | `APIStatusError`           |
+| Timeout          | `APITimeoutError`          |
+| Network error    | `APIConnectionError`       |
+
+### Retries
+
+Certain errors will be automatically retried 1 times by default, with a short
+exponential backoff. Connection errors (for example, due to a network
+connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors,
+and timeouts will all be retried by default.
+
+You can use the `max_retries` option to configure or disable this:
+
+```ruby
+# Configure the default for all requests:
+sink = Sink::Client.new(
+  max_retries: 0, # default is 1
+  username: "Robert",
+  some_number_arg_required_no_default: 0,
+  some_number_arg_required_no_default_no_env: 0,
+  required_arg_no_env: "<example>"
+)
+
+# Or, configure per-request:
+sink.cards.provision_foo("my card token", digital_wallet: "GOOGLE_PAY", max_retries: 5)
+```
+
+### Timeouts
+
+By default, requests will time out after 60 seconds.
+Timeouts are applied separately to the initial connection and the overall request time,
+so in some cases a request could wait 2\*timeout seconds before it fails.
+
+You can use the `timeout` option to configure or disable this:
+
+```ruby
+# Configure the default for all requests:
+sink = Sink::Client.new(
+  timeout: nil, # default is 60
+  username: "Robert",
+  some_number_arg_required_no_default: 0,
+  some_number_arg_required_no_default_no_env: 0,
+  required_arg_no_env: "<example>"
+)
+
+# Or, configure per-request:
+sink.cards.create(type: "DIGITAL", timeout: 5)
+```
+
+## Versioning
+
+This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the
+library is in initial development and has a major version of `0`, APIs may change
+at any time.
+
+## Requirements
+
+Ruby 3.0 or higher.

data/lib/sink/base_client.rb

@@ -0,0 +1,404 @@
+# frozen_string_literal: true
+
+module Sink
+  # @!visibility private
+  class BaseClient
+    attr_accessor :requester
+
+    # @param base_url [String]
+    # @param timeout [Integer, nil]
+    # @param headers [Hash{String => String}]
+    # @param max_retries [Integer]
+    # @param idempotency_header [String, nil]
+    def initialize(
+      base_url:,
+      timeout: nil,
+      headers: {},
+      max_retries: 0,
+      idempotency_header: nil
+    )
+      self.requester = PooledNetRequester.new
+      base_url_parsed = URI.parse(base_url)
+      @headers = Util.normalized_headers(
+        {
+          "X-Stainless-Lang" => "ruby",
+          "X-Stainless-Package-Version" => Sink::VERSION,
+          "X-Stainless-Runtime" => RUBY_ENGINE,
+          "X-Stainless-Runtime-Version" => RUBY_ENGINE_VERSION,
+          "Accept" => "application/json"
+        },
+        headers
+      )
+      @host = base_url_parsed.host
+      @scheme = base_url_parsed.scheme
+      @port = base_url_parsed.port
+      @base_path = self.class.normalize_path(base_url_parsed.path)
+      @max_retries = max_retries
+      @timeout = timeout
+      @idempotency_header = idempotency_header
+    end
+
+    # @return [Hash{String => String}]
+    def auth_headers
+      {}
+    end
+
+    def validate_request(req, opts)
+      if (body = req[:body])
+        # Body can be at least a Hash or Array, just check for Hash shape for now.
+        if body.is_a?(Hash)
+          body.each_key do |k|
+            unless k.is_a?(Symbol)
+              raise ArgumentError, "Request body keys must be Symbols, got #{k.inspect}"
+            end
+          end
+        end
+      end
+
+      unless opts.is_a?(Hash) || opts.is_a?(Sink::RequestOption)
+        raise ArgumentError, "Request `opts` must be a Hash or RequestOptions, got #{opts.inspect}"
+      end
+      opts.to_h.each_key do |k|
+        unless k.is_a?(Symbol)
+          raise ArgumentError, "Request `opts` keys must be Symbols, got #{k.inspect}"
+        end
+        unless (valid_keys = Sink::RequestOptions.options).include?(k)
+          raise ArgumentError, "Request `opts` keys must be one of #{valid_keys}, got #{k.inspect}"
+        end
+      end
+    end
+
+    def self.normalize_path(path)
+      path.gsub(/\/+/, "/")
+    end
+
+    def resolve_uri_elements(req)
+      from_args =
+        if req[:url]
+          uri = req[:url].is_a?(URI::Generic) ? req[:url] : URI.parse(req[:url])
+          {
+            host: uri.host,
+            scheme: uri.scheme,
+            path: uri.path,
+            query: CGI.parse(uri.query || ""),
+            port: uri.port
+          }
+        else
+          from_req = req.slice(:host, :scheme, :path, :port, :query)
+          from_req[:path] = self.class.normalize_path("/#{@base_path}/#{from_req[:path]}")
+          from_req
+        end
+
+      uri_components = {host: @host, scheme: @scheme, port: @port}.merge(from_args)
+
+      if req[:extra_query]
+        uri_components[:query] = Util.deep_merge(uri_components[:query], req[:extra_query], concat: true)
+      end
+
+      uri_components
+    end
+
+    def prep_request(options)
+      method = options.fetch(:method)
+
+      headers = Util.normalized_headers(@headers, auth_headers, options[:headers], options[:extra_headers])
+      if @idempotency_header && !headers[@idempotency_header] && ![:get, :head, :options].include?(method)
+        headers[@idempotency_header.to_s.downcase] = options[:idempotency_key] || generate_idempotency_key
+      end
+      if !headers.key?("x-stainless-retry-count")
+        headers["x-stainless-retry-count"] = "0"
+      end
+      headers.compact!
+      headers.transform_values!(&:to_s)
+
+      body =
+        case method
+        when :post, :put, :patch, :delete
+          body = options[:body]
+          if body
+            if headers["content-type"] == "application/json"
+              JSON.dump(body)
+            else
+              body
+            end
+          end
+        else
+          nil
+        end
+      if options[:extra_body]
+        body = Util.deep_merge(body, options[:extra_body])
+      end
+
+      url_elements = resolve_uri_elements(options)
+
+      {method: method, headers: headers, body: body}.merge(url_elements)
+    end
+
+    def generate_idempotency_key
+      "stainless-ruby-retry-#{SecureRandom.uuid}"
+    end
+
+    def should_retry?(response)
+      should_retry_header = response["x-should-retry"]
+
+      case should_retry_header
+      when "true"
+        true
+      when "false"
+        false
+      else
+        response_code = response.code.to_i
+        # retry on:
+        # 408: timeouts
+        # 409: locks
+        # 429: rate limits
+        # 500+: unknown errors
+        [408, 409, 429].include?(response_code) || response_code >= 500
+      end
+    end
+
+    def make_status_error(message:, body:, response:)
+      raise NotImplementedError
+    end
+
+    def make_status_error_from_response(response)
+      err_body =
+        begin
+          JSON.parse(response.body)
+        rescue StandardError
+          response
+        end
+
+      # We include the body in the error message as well as returning it
+      # since logging error messages is a common and quick way to assess what's
+      # wrong with a response.
+      message = "Error code: #{response.code}; Response: #{response.body}"
+
+      make_status_error(message: message, body: err_body, response: response)
+    end
+
+    def header_based_retry(response)
+      # Note the `retry-after-ms` header may not be standard, but is a good idea and we'd like proactive support for it.
+      retry_after_millis = Float(response["retry-after-ms"], exception: false)
+      if retry_after_millis
+        retry_after = retry_after_millis / 1000.0
+      elsif response["retry-after"]
+        retry_after = Float(response["retry-after"], exception: false)
+        if retry_after.nil?
+          begin
+            base = Time.now
+            if response["x-stainless-mock-sleep-base"]
+              base = Time.httpdate(response["x-stainless-mock-sleep-base"])
+            end
+            retry_after = Time.httpdate(response["retry-after"]) - base
+          rescue StandardError # rubocop:disable Lint/SuppressedException
+          end
+        end
+      end
+      retry_after
+    rescue StandardError # rubocop:disable Lint/SuppressedException
+    end
+
+    def send_request(request, max_retries:, timeout:, redirect_count:)
+      delay = 0.6
+      max_delay = 8.0
+      # Don't send the current retry count in the headers if the caller modified the header defaults.
+      should_send_retry_count = request[:headers]["x-stainless-retry-count"] == "0"
+      retries = 0
+      loop do # rubocop:disable Metrics/BlockLength
+        if should_send_retry_count
+          request[:headers]["x-stainless-retry-count"] = retries.to_s
+        end
+
+        begin
+          response = @requester.execute(request, timeout: timeout)
+          status = response.code.to_i
+
+          if status < 300
+            return response
+          elsif status < 400
+            begin
+              prev_uri = URI.parse(Util.uri_from_req(request, absolute: true))
+              location = URI.join(prev_uri, response["location"])
+            rescue ArgumentError
+              message = "server responded with status #{status} but no valid location header"
+              raise HTTP::APIConnectionError.new(message: message, request: request)
+            end
+            # from whatwg fetch spec
+            if redirect_count == 20
+              message = "failed to complete the request within 20 redirects"
+              raise HTTP::APIConnectionError.new(message: message, request: request)
+            end
+            if location.scheme != "http" && location.scheme != "https"
+              message = "tried to redirect to a non-http URL"
+              raise HTTP::APIConnectionError.new(message: message, request: request)
+            end
+            request = request.merge(resolve_uri_elements({url: location}))
+            # from whatwg fetch spec
+            if ([301, 302].include?(status) && request[:method] == :post) || (status == 303)
+              request[:method] = request[:method] == :head ? :head : :get
+              request[:body] = nil
+              request[:headers] = request[:headers].reject do |k|
+                %w[content-encoding content-language content-location content-type content-length].include?(k)
+              end
+            end
+            # from undici
+            if Sink::Util.uri_origin(prev_uri) != Sink::Util.uri_origin(location)
+              request[:headers] = request[:headers].reject do |k|
+                %w[authorization cookie proxy-authorization host].include?(k)
+              end
+            end
+            return send_request(
+              request,
+              max_retries: max_retries,
+              timeout: timeout,
+              redirect_count: redirect_count + 1
+            )
+          end
+        rescue Net::HTTPBadResponse
+          if retries >= max_retries
+            message = "failed to complete the request within #{max_retries} retries"
+            raise HTTP::APIConnectionError.new(message: message, request: request)
+          end
+        rescue Timeout::Error
+          if retries >= max_retries
+            message = "failed to complete the request within #{max_retries} retries"
+            raise HTTP::APITimeoutError.new(message: message, request: request)
+          end
+        end
+
+        if (response && !should_retry?(response)) || retries >= max_retries
+          raise make_status_error_from_response(response)
+        end
+
+        retries += 1
+        base_delay = header_based_retry(response)
+        if base_delay
+          delay = base_delay
+        else
+          base_delay = (delay * (2**retries))
+          jitter_factor = 1 - (0.25 * rand)
+          delay = (base_delay * jitter_factor).clamp(0, max_delay)
+        end
+
+        if response&.key?("x-stainless-mock-sleep")
+          request[:headers]["x-stainless-mock-slept"] = delay
+        else
+          sleep(delay)
+        end
+      end
+    end
+
+    # Execute the request specified by req + opts. This is the method that all
+    # resource methods call into.
+    # Params req & opts are kept separate up until this point so that we can
+    # validate opts as it was given to us by the user.
+    def request(req, opts)
+      validate_request(req, opts)
+      options = Util.deep_merge(req, opts)
+      request_args = prep_request(options)
+      response = send_request(
+        request_args,
+        max_retries: opts.fetch(:max_retries, @max_retries),
+        timeout: opts.fetch(:timeout, @timeout),
+        redirect_count: 0
+      )
+      raw_data =
+        case response.content_type
+        when "application/json"
+          begin
+            data = JSON.parse(response.body, symbolize_names: true)
+            req[:unwrap] ? data[req[:unwrap]] : data
+          rescue JSON::ParserError
+            response.body
+          end
+          # TODO: parsing other response types
+        else
+          response.body
+        end
+
+      if (page = req[:page])
+        model = req.fetch(:model)
+        page.new(model, raw_data, response, self, req, opts)
+      elsif (model = req[:model])
+        Converter.convert(model, raw_data)
+      else
+        raw_data
+      end
+    end
+
+    # @return [String]
+    def inspect
+      base_url = Util.uri_from_req(
+        {host: @host, scheme: @scheme, port: @port, path: @base_path},
+        absolute: true
+      )
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} base_url=#{base_url.inspect} max_retries=#{@max_retries.inspect} timeout=#{@timeout.inspect}>"
+    end
+  end
+
+  class Error < StandardError
+  end
+
+  module HTTP
+    class Error < Sink::Error
+    end
+
+    class ResponseError < Error
+      attr_reader :response, :body
+
+      # @!attribute [r] code
+      #   @return [Integer]
+      attr_reader :code
+
+      def initialize(message:, response:, body:)
+        super(message)
+        @response = response
+        @body = body
+        @code = response.code.to_i
+      end
+    end
+
+    class RequestError < Error
+      attr_reader :request
+
+      def initialize(message:, request:)
+        super(message)
+        @request = request
+      end
+    end
+
+    class BadRequestError < ResponseError
+    end
+
+    class AuthenticationError < ResponseError
+    end
+
+    class PermissionDeniedError < ResponseError
+    end
+
+    class NotFoundError < ResponseError
+    end
+
+    class ConflictError < ResponseError
+    end
+
+    class UnprocessableEntityError < ResponseError
+    end
+
+    class RateLimitError < ResponseError
+    end
+
+    class InternalServerError < ResponseError
+    end
+
+    class APIStatusError < ResponseError
+    end
+
+    class APIConnectionError < RequestError
+    end
+
+    class APITimeoutError < RequestError
+    end
+  end
+end