tungo-sdk 0.2.0

data/lib/tungo/money.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Tungo
+  # Money helpers. The API expresses amounts in tiyn (1/100 of a tenge) as 64-bit integers.
+  # Conversion is exact: no binary floating point is involved for String, Integer, BigDecimal
+  # and Rational input.
+  module Money
+    INT64 = (-(2**63)..((2**63) - 1))
+    DECIMAL = /\A(-?)([0-9]+)(?:\.([0-9]+))?\z/
+    SYMBOLS = { "" => "₸", "KZT" => "₸", "USD" => "$", "EUR" => "€", "RUB" => "₽" }.freeze
+    BIN_IIN = /\A[0-9]{12}\z/
+    private_constant :DECIMAL, :SYMBOLS, :BIN_IIN
+
+    module_function
+
+    # Converts an amount in tenge to tiyn, rounding half away from zero to two decimal places.
+    #
+    #   Tungo::Money.to_tiyn("1.005")             # => 101
+    #   Tungo::Money.to_tiyn(BigDecimal("45000")) # => 4_500_000
+    #
+    # @param amount [String, Integer, BigDecimal, Rational, Float] a String must match
+    #   +-?digits[.digits]+; a Float is converted through its shortest decimal representation
+    # @return [Integer] tiyn, within int64
+    # @raise [Tungo::MoneyError] malformed, non-finite or out-of-range input
+    def to_tiyn(amount)
+      tiyn = case amount
+             when String then decimal_to_tiyn(amount)
+             when Integer then amount * 100
+             when BigDecimal, Float then decimal_to_tiyn(finite_decimal(amount).to_s("F"))
+             when Rational then rational_to_tiyn(amount)
+             else raise MoneyError, "cannot convert #{amount.class} to tiyn"
+             end
+      check_range(tiyn)
+    end
+
+    # @param tiyn [Integer]
+    # @return [BigDecimal] the exact amount in tenge
+    def to_tenge(tiyn)
+      BigDecimal(check_integer(tiyn)) / 100
+    end
+
+    # Formats tiyn for display: +4500000+ becomes "45 000,00 ₸".
+    #
+    # @param tiyn [Integer]
+    # @param currency [String] ISO code; KZT, USD, EUR and RUB get their symbol, others the code
+    # @return [String]
+    def format_tiyn(tiyn, currency = "KZT")
+      tiyn = check_range(check_integer(tiyn))
+      code = currency.to_s.upcase
+      whole, fraction = tiyn.abs.divmod(100)
+      grouped = whole.to_s.reverse.scan(/[0-9]{1,3}/).join(" ").reverse
+      "#{"-" if tiyn.negative?}#{grouped},#{fraction.to_s.rjust(2, "0")} #{SYMBOLS.fetch(code, code)}"
+    end
+
+    # Checks a Kazakhstan BIN/IIN: exactly 12 ASCII digits with a valid check digit. The input
+    # is not trimmed.
+    #
+    # @param value [String]
+    # @return [Boolean]
+    def valid_bin_iin?(value)
+      return false unless value.is_a?(String) && BIN_IIN.match?(value)
+
+      digits = value.bytes.map { |byte| byte - 48 }
+      check = bin_iin_checksum(digits, 1)
+      check = bin_iin_checksum(digits, 3) if check == 10
+      check < 10 && check == digits[11]
+    end
+
+    # @api private
+    def decimal_to_tiyn(text)
+      match = text.encoding.ascii_compatible? ? DECIMAL.match(text) : nil
+      raise MoneyError, "#{text.inspect} is not a decimal amount (expected -?digits[.digits])" unless match
+
+      fraction = "#{match[3]}000"
+      tiyn = "#{match[2]}#{fraction[0, 2]}".to_i
+      tiyn += 1 if fraction[2] >= "5"
+      match[1] == "-" ? -tiyn : tiyn
+    end
+
+    # @api private
+    def rational_to_tiyn(amount)
+      tiyn = ((amount.abs * 100) + Rational(1, 2)).floor
+      amount.negative? ? -tiyn : tiyn
+    end
+
+    # @api private
+    def finite_decimal(amount)
+      raise MoneyError, "#{amount} is not a finite amount" unless amount.finite?
+
+      amount.is_a?(Float) ? BigDecimal(amount.to_s) : amount
+    end
+
+    # @api private
+    def check_integer(tiyn)
+      raise MoneyError, "tiyn must be an Integer, got #{tiyn.class}" unless tiyn.is_a?(Integer)
+
+      tiyn
+    end
+
+    # @api private
+    def check_range(tiyn)
+      raise MoneyError, "#{tiyn} tiyn does not fit into a 64-bit integer" unless INT64.cover?(tiyn)
+
+      tiyn
+    end
+
+    # @api private
+    def bin_iin_checksum(digits, first_weight)
+      (0...11).sum { |index| digits[index] * (((first_weight - 1 + index) % 11) + 1) } % 11
+    end
+  end
+end

data/lib/tungo/page.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Tungo
+  # One page of a cursor-paginated list (+{ data, next_cursor }+).
+  #
+  #   page = client.chat.list(limit: 20)
+  #   page.data            # the items of this page
+  #   page.next_page?      # is there another page?
+  #   page = page.next_page
+  #
+  # A page is Enumerable over its own items. {#auto_paging_each} walks this page and all the
+  # following ones, fetching each page only when it is needed.
+  class Page
+    include Enumerable
+
+    # @return [Array] the typed items of this page
+    attr_reader :data
+    # @return [String, nil] cursor of the next page; nil or empty on the last page
+    attr_reader :next_cursor
+    # @return [Tungo::Model] the whole response object (it may carry more than data and next_cursor)
+    attr_reader :body
+    # @return [Tungo::APIResponse] status and headers of the response
+    attr_reader :api_response
+
+    # @api private
+    def initialize(body:, cursor:, fetch:, seen: nil)
+      @body = body
+      data = body[:data]
+      @data = data.is_a?(Array) ? data : [].freeze
+      next_cursor = body[:next_cursor]
+      @next_cursor = next_cursor.is_a?(String) && !next_cursor.empty? ? next_cursor : nil
+      @api_response = body.api_response
+      @cursor = cursor
+      @seen = (seen || [cursor].compact).freeze
+      @fetch = fetch
+      freeze
+    end
+
+    # Yields the items of this page only.
+    def each(&)
+      return enum_for(:each) unless block_given?
+
+      @data.each(&)
+      self
+    end
+
+    # @return [Boolean] whether another page exists
+    def next_page?
+      !@next_cursor.nil?
+    end
+
+    # Fetches the next page with the same filters.
+    #
+    # @return [Tungo::Page]
+    # @raise [Tungo::PaginationError] when this is the last page or the API returns a cursor that
+    #   was already used on the way to this page
+    def next_page
+      raise PaginationError, "there is no next page: next_cursor is empty" unless next_page?
+      if @seen.include?(@next_cursor)
+        raise PaginationError,
+              "the API returned the cursor #{@next_cursor.inspect} twice; stopping instead of looping forever"
+      end
+
+      @fetch.call(@next_cursor, @seen)
+    end
+
+    # Iterates over the items of this page and of every following page. Pages are requested
+    # lazily: stopping early stops fetching.
+    #
+    # @return [Enumerator] when no block is given
+    def auto_paging_each(&)
+      first = self
+      self.class.auto_paging { first }.each(&)
+    end
+
+    # @api private
+    # @return [Enumerator] a lazy iterator over all items, starting with the page the block returns
+    def self.auto_paging
+      Enumerator.new do |yielder|
+        page = yield
+        loop do
+          page.data.each { |item| yielder << item }
+          break unless page.next_page?
+
+          page = page.next_page
+        end
+      end
+    end
+
+    def inspect
+      "#<#{self.class.name} data=#{@data.size} items next_cursor=#{@next_cursor.inspect}>"
+    end
+  end
+end

data/lib/tungo/request_options.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Tungo
+  # Per-request overrides. Every resource method takes +request_options:+ as a Hash with the
+  # same keys or as an instance of this class.
+  #
+  # @!attribute timeout
+  #   @return [Numeric, nil] seconds for the whole request, including reading the body
+  # @!attribute max_retries
+  #   @return [Integer, nil] how many times a failed request may be repeated
+  # @!attribute idempotency_key
+  #   @return [String, nil] value of the Idempotency-Key header (generated when the operation declares it)
+  # @!attribute extra_headers
+  #   @return [Hash{String=>String}, nil] headers added to (or replacing) the default ones
+  # @!attribute connect_timeout
+  #   @return [Numeric, nil] seconds to establish the connection of a streaming call
+  # @!attribute idle_timeout
+  #   @return [Numeric, nil] seconds a streaming call may stay silent
+  RequestOptions = Data.define(:timeout, :max_retries, :idempotency_key, :extra_headers, :connect_timeout,
+                               :idle_timeout) do
+    def initialize(timeout: nil, max_retries: nil, idempotency_key: nil, extra_headers: nil, connect_timeout: nil,
+                   idle_timeout: nil)
+      self.class.check_seconds(:timeout, timeout)
+      self.class.check_seconds(:connect_timeout, connect_timeout)
+      self.class.check_seconds(:idle_timeout, idle_timeout)
+      unless max_retries.nil? || (max_retries.is_a?(Integer) && !max_retries.negative?)
+        raise ValidationError, "max_retries must be a non-negative Integer"
+      end
+      unless idempotency_key.nil? || (idempotency_key.is_a?(String) && !idempotency_key.empty?)
+        raise ValidationError, "idempotency_key must be a non-empty String"
+      end
+
+      super(timeout:, max_retries:, idempotency_key:, extra_headers: extra_headers&.to_h&.freeze, connect_timeout:,
+            idle_timeout:)
+    end
+
+    # @param value [Tungo::RequestOptions, Hash, nil]
+    # @return [Tungo::RequestOptions]
+    def self.coerce(value)
+      case value
+      when RequestOptions then value
+      when nil then new
+      when Hash then new(**value.transform_keys(&:to_sym))
+      else raise ValidationError, "request_options must be a Hash or a Tungo::RequestOptions, got #{value.class}"
+      end
+    rescue ArgumentError => e
+      raise ValidationError, "invalid request_options: #{e.message}"
+    end
+
+    # @api private
+    def self.check_seconds(name, value)
+      return if value.nil? || (value.is_a?(Numeric) && value.positive? && value.to_f.finite?)
+
+      raise ValidationError, "#{name} must be a positive number of seconds"
+    end
+  end
+end

data/lib/tungo/resources/api_keys.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# Code generated by tungo-sdkgen from the Tungo Platform API contract. DO NOT EDIT.
+
+module Tungo
+  module Resources
+    # Сведения о текущем ключе API и статистика его расхода
+    class ApiKeys
+      # @api private
+      def initialize(client)
+        @client = client
+        freeze
+      end
+
+      # Ключ, по которому пришёл запрос (кто я)
+      #
+      # +GET /v1/api-key+
+      #
+      # @param request_options [Tungo::RequestOptions, Hash, nil] per-request overrides
+      # @return [Tungo::Models::ApiKeySelf]
+      def get_current(request_options: nil)
+        @client.request(
+          method: :get,
+          path: "/v1/api-key",
+          model: :ApiKeySelf,
+          options: request_options
+        )
+      end
+
+      # Расход ключа, по которому пришёл запрос
+      #
+      # +GET /v1/api-key/usage+
+      #
+      # @param from [String, nil] Начало периода, ISO 8601 (включительно). Нет — 1-е число текущего месяца,
+      #   00:00 по Алматы
+      # @param to [String, nil] Конец периода, ISO 8601 (не включительно); позже from и не дальше 400 дней
+      #   от него. Нет — сейчас
+      # @param request_options [Tungo::RequestOptions, Hash, nil] per-request overrides
+      # @return [Tungo::Models::ApiKeyUsage]
+      def get_current_usage(from: OMIT, to: OMIT, request_options: nil)
+        @client.request(
+          method: :get,
+          path: "/v1/api-key/usage",
+          query: { "from" => from, "to" => to },
+          model: :ApiKeyUsage,
+          options: request_options
+        )
+      end
+
+      # Расход ключа за период
+      #
+      # +GET /v1/workspaces/{ws}/api-keys/{id}/usage+
+      #
+      # @param id [String] id ключа (key_…)
+      # @param from [String, nil] Начало периода, ISO 8601 (включительно). Нет — 1-е число текущего месяца,
+      #   00:00 по Алматы
+      # @param to [String, nil] Конец периода, ISO 8601 (не включительно); позже from и не дальше 400 дней
+      #   от него. Нет — сейчас
+      # @param workspace_id [String, nil] overrides the client's workspace
+      # @param request_options [Tungo::RequestOptions, Hash, nil] per-request overrides
+      # @return [Tungo::Models::ApiKeyUsage]
+      def get_usage(id, from: OMIT, to: OMIT, workspace_id: nil, request_options: nil)
+        @client.request(
+          method: :get,
+          path: "/v1/workspaces/{ws}/api-keys/{id}/usage",
+          path_params: { ws: @client.resolve_workspace_id(workspace_id), id: id },
+          query: { "from" => from, "to" => to },
+          model: :ApiKeyUsage,
+          options: request_options
+        )
+      end
+    end
+  end
+end