flat_api 0.2.0 → 1.0.0

data/lib/flat_api/models/user_signin_link_creation.rb

@@ -0,0 +1,150 @@
+=begin
+#Flat API
+
+#The Flat API allows you to easily extend the abilities of the [Flat Platform](https://flat.io), with a wide range of use cases including the following:  * Creating and importing new music scores using MusicXML, MIDI, Guitar Pro, MuseScore, ABC notation, and many other formats * Browsing, updating, copying, exporting the user's scores (for example in MP3, WAV or MIDI) * Managing educational resources with Flat for Education: creating & updating the organization accounts, the classes, rosters and assignments.  The Flat API is built on HTTP. Our API is RESTful It has predictable resource URLs. It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body. The [schema](/swagger.yaml) of this API follows the [OpenAPI Initiative (OAI) specification](https://www.openapis.org/), you can use and work with [compatible Swagger tools](http://swagger.io/open-source-integrations/). This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with [W3C spec](https://www.w3.org/TR/cors/).  You can use your favorite HTTP/REST library for your programming language to use Flat's API. This specification and reference is [available on Github](https://github.com/FlatIO/api-reference).  Getting Started and learn more:  * [API Overview and introduction](https://flat.io/developers/docs/api/) * [Authentication (Personal Access Tokens or OAuth2)](https://flat.io/developers/docs/api/authentication.html) * [SDKs](https://flat.io/developers/docs/api/sdks.html) * [Rate Limits](https://flat.io/developers/docs/api/rate-limits.html) * [Changelog](https://flat.io/developers/docs/api/changelog.html) 
+
+The version of the OpenAPI document: 2.26.1
+Contact: developers@flat.io
+Generated by: https://openapi-generator.tech
+Generator version: 7.24.0
+
+=end
+
+require 'date'
+require 'time'
+
+module FlatApi
+  class UserSigninLinkCreation < ApiModelBase
+    # Path to redirect to after signin
+    attr_accessor :destination_path
+
+    # Attribute mapping from ruby-style variable name to JSON key.
+    def self.attribute_map
+      {
+        :'destination_path' => :'destinationPath'
+      }
+    end
+
+    # Returns attribute mapping this model knows about
+    def self.acceptable_attribute_map
+      attribute_map
+    end
+
+    # Returns all the JSON keys this model knows about
+    def self.acceptable_attributes
+      acceptable_attribute_map.values
+    end
+
+    # Attribute type mapping.
+    def self.openapi_types
+      {
+        :'destination_path' => :'String'
+      }
+    end
+
+    # List of attributes with nullable: true
+    def self.openapi_nullable
+      Set.new([
+      ])
+    end
+
+    # Initializes the object
+    # @param [Hash] attributes Model attributes in the form of hash
+    def initialize(attributes = {})
+      if (!attributes.is_a?(Hash))
+        fail ArgumentError, "The input argument (attributes) must be a hash in `FlatApi::UserSigninLinkCreation` initialize method"
+      end
+
+      # check to see if the attribute exists and convert string to symbol for hash key
+      acceptable_attribute_map = self.class.acceptable_attribute_map
+      attributes = attributes.each_with_object({}) { |(k, v), h|
+        if (!acceptable_attribute_map.key?(k.to_sym))
+          fail ArgumentError, "`#{k}` is not a valid attribute in `FlatApi::UserSigninLinkCreation`. Please check the name to make sure it's valid. List of attributes: " + acceptable_attribute_map.keys.inspect
+        end
+        h[k.to_sym] = v
+      }
+
+      if attributes.key?(:'destination_path')
+        self.destination_path = attributes[:'destination_path']
+      else
+        self.destination_path = '/'
+      end
+    end
+
+    # Show invalid properties with the reasons. Usually used together with valid?
+    # @return Array for valid properties with the reasons
+    def list_invalid_properties
+      warn '[DEPRECATED] the `list_invalid_properties` method is obsolete'
+      invalid_properties = Array.new
+      invalid_properties
+    end
+
+    # Check to see if the all the properties in the model are valid
+    # @return true if the model is valid
+    def valid?
+      warn '[DEPRECATED] the `valid?` method is obsolete'
+      true
+    end
+
+    # Checks equality by comparing each attribute.
+    # @param [Object] Object to be compared
+    def ==(o)
+      return true if self.equal?(o)
+      self.class == o.class &&
+          destination_path == o.destination_path
+    end
+
+    # @see the `==` method
+    # @param [Object] Object to be compared
+    def eql?(o)
+      self == o
+    end
+
+    # Calculates hash code according to all attributes.
+    # @return [Integer] Hash code
+    def hash
+      [destination_path].hash
+    end
+
+    # Builds the object from hash
+    # @param [Hash] attributes Model attributes in the form of hash
+    # @return [Object] Returns the model itself
+    def self.build_from_hash(attributes)
+      return nil unless attributes.is_a?(Hash)
+      attributes = attributes.transform_keys(&:to_sym)
+      transformed_hash = {}
+      openapi_types.each_pair do |key, type|
+        if attributes.key?(attribute_map[key]) && attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = nil
+        elsif type =~ /\AArray<(.*)>/i
+          # check to ensure the input is an array given that the attribute
+          # is documented as an array but the input is not
+          if attributes[attribute_map[key]].is_a?(Array)
+            transformed_hash["#{key}"] = attributes[attribute_map[key]].map { |v| _deserialize($1, v) }
+          end
+        elsif !attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = _deserialize(type, attributes[attribute_map[key]])
+        end
+      end
+      new(transformed_hash)
+    end
+
+    # Returns the object in the form of hash
+    # @return [Hash] Returns the object in the form of hash
+    def to_hash
+      hash = {}
+      self.class.attribute_map.each_pair do |attr, param|
+        value = self.send(attr)
+        if value.nil?
+          is_nullable = self.class.openapi_nullable.include?(attr)
+          next if !is_nullable || (is_nullable && !instance_variable_defined?(:"@#{attr}"))
+        end
+
+        hash[param] = _to_hash(value)
+      end
+      hash
+    end
+
+  end
+
+end

data/lib/flat_api/oauth.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+require 'flat_api/errors'
+
+# OAuth2 support for the Flat API.
+#
+# The public specification declares one security scheme: OAuth2 authorization-code with 23 scopes.
+# A Personal Access Token is an OAuth access token for your own account, so passing a token straight
+# to the client covers both cases.
+#
+# A refresh token is only issued when the authorization request sets access_type=offline.
+#
+# This module never stores a token. Persistence is deployment-specific, so refreshed tokens go to a
+# callback you supply.
+module FlatApi
+  AUTHORIZE_URL = 'https://flat.io/auth/oauth'
+  TOKEN_URL = 'https://api.flat.io/oauth/access_token'
+  # Refresh slightly before nominal expiry, to avoid racing the server clock.
+  EXPIRY_SKEW = 30
+
+  Tokens = Struct.new(:access_token, :refresh_token, :expires_at, keyword_init: true) do
+    def self.from_response(payload)
+      expires_in = payload['expires_in']
+      new(
+        access_token: payload['access_token'],
+        refresh_token: payload['refresh_token'],
+        expires_at: expires_in ? Time.now.to_i + expires_in.to_i : nil
+      )
+    end
+
+    def expired?
+      !expires_at.nil? && Time.now.to_i >= expires_at - EXPIRY_SKEW
+    end
+  end
+
+  # Builds the authorization URL and exchanges codes for tokens.
+  class OAuth2Helper
+    def initialize(client_id:, client_secret:, redirect_uri:)
+      @client_id = client_id
+      @client_secret = client_secret
+      @redirect_uri = redirect_uri
+    end
+
+    # URL to send a user to. +offline+ is what yields a refresh token.
+    def authorize_url(scopes:, state:, offline: true)
+      params = {
+        client_id: @client_id, redirect_uri: @redirect_uri, response_type: 'code',
+        scope: Array(scopes).join(' '), state: state
+      }
+      params[:access_type] = 'offline' if offline
+      "#{AUTHORIZE_URL}?#{URI.encode_www_form(params)}"
+    end
+
+    def exchange_code(code)
+      token_request(grant_type: 'authorization_code', code: code, redirect_uri: @redirect_uri)
+    end
+
+    def refresh(refresh_token)
+      token_request(grant_type: 'refresh_token', refresh_token: refresh_token)
+    end
+
+    private
+
+    def token_request(**payload)
+      response = Net::HTTP.post_form(
+        URI(TOKEN_URL), payload.merge(client_id: @client_id, client_secret: @client_secret)
+      )
+      unless response.is_a?(Net::HTTPSuccess)
+        raise FlatAuthenticationError.new(
+          'OAuth2 token request failed; the user must re-authorize', status: response.code.to_i
+        )
+      end
+
+      Tokens.from_response(JSON.parse(response.body))
+    end
+  end
+
+  # Holds the current tokens and refreshes them at most once at a time.
+  #
+  # Single-flight matters: two concurrent requests hitting an expired token must not both refresh,
+  # because the second refresh would invalidate the token the first just obtained.
+  class TokenManager
+    def initialize(tokens, helper: nil, on_token_refresh: nil)
+      @tokens = tokens
+      @helper = helper
+      @on_token_refresh = on_token_refresh
+      @mutex = Mutex.new
+    end
+
+    # Refreshes when the token has expired, which is the whole point of a TokenManager: a caller
+    # installs this as Configuration#access_token_getter and never thinks about expiry again.
+    # Returning @tokens.access_token unconditionally made Tokens#expired? dead code, and every
+    # request after the expiry failed with a 401 that a refresh would have avoided.
+    def access_token
+      return @tokens.access_token unless @tokens.expired?
+
+      @mutex.synchronize do
+        # Checked again inside the lock: a thread that waited here may find the token already
+        # refreshed, and refreshing twice would spend a second round trip and, with a provider
+        # that rotates refresh tokens, invalidate the one the first thread just stored.
+        next @tokens.access_token unless @tokens.expired?
+
+        refresh_locked
+      end
+    end
+
+    # Refreshes unconditionally. Use it to force a refresh; access_token already handles expiry.
+    def refresh
+      @mutex.synchronize { refresh_locked }
+    end
+
+    private
+
+    def refresh_locked
+      if @helper.nil? || @tokens.refresh_token.nil?
+        raise FlatAuthenticationError,
+              'the access token expired and no refresh token is available; re-authorize'
+      end
+
+      @tokens = @helper.refresh(@tokens.refresh_token)
+      @on_token_refresh&.call(@tokens)
+      @tokens.access_token
+    end
+  end
+end

data/lib/flat_api/pagination.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# Cursor pagination for the Flat API.
+#
+# Eight operations at v2.25.0 are cursor-paginated, identified by a +next+ query parameter. That
+# parameter is a shared component (#/components/parameters/next): any tool that reads an
+# operation's parameters without resolving $ref under-counts them and ships collections that
+# silently truncate.
+#
+# The cursor is not in the response body. It arrives in the Link header, which the specification
+# does not declare, so it is parsed at runtime.
+require 'uri'
+
+module FlatApi
+  module Pagination
+    LINK = /<([^>]+)>\s*;\s*rel="([^"]+)"/.freeze
+
+    module_function
+
+    # Parse an RFC 5988 Link header into { rel => url }.
+    def parse_link_header(value)
+      return {} if value.nil? || value.empty?
+
+      value.scan(LINK).to_h { |url, rel| [rel, url] }
+    end
+
+    # Extract the opaque +next+ cursor from a response's Link header, if any.
+    #
+    # Decoded, not captured raw. The cursor arrives percent-encoded inside the Link header's
+    # URL, and the client encodes whatever it is given when building the next request, so
+    # passing the encoded form through sends it encoded twice and the server rejects the very
+    # cursor it issued. URI.decode_www_form applies the rules the server used to write it, so
+    # an opaque value round-trips exactly.
+    def next_cursor(headers)
+      return nil if headers.nil?
+
+      _, link = headers.find { |k, _| k.to_s.downcase == 'link' }
+      url = parse_link_header(link)['next']
+      return nil if url.nil?
+
+      query = begin
+        URI.parse(url).query
+      rescue URI::InvalidURIError
+        nil
+      end
+      return nil if query.nil? || query.empty?
+
+      URI.decode_www_form(query).assoc('next')&.last
+    end
+
+    # Every item across all pages of a cursor-paginated operation, as a lazy Enumerator.
+    #
+    # +fetch_page+ is called with a params hash and must return [data, status, headers], which is
+    # exactly what the generated *_with_http_info methods return. The cursor lives in the headers.
+    #
+    # A token expiring mid-traversal is refreshed by the client and the traversal resumes from the
+    # same cursor, so no page is skipped or repeated.
+    #
+    #   FlatApi::Pagination.paginate(user: 'me') do |params|
+    #     api.get_user_scores_with_http_info('me', params)
+    #   end.each { |score| puts score.title }
+    def paginate(**params, &fetch_page)
+      raise ArgumentError, 'paginate requires a block that fetches one page' unless fetch_page
+
+      Enumerator.new do |yielder|
+        # +_next+, not +next+. `next` is a Ruby keyword, so the generator names the option
+        # +:_next+ and maps it back to the +next+ query parameter itself. Passing +:next+ here
+        # sends nothing: every iteration refetches page one, the loop guard below sees a cursor it
+        # has already used, and the traversal stops after the first page while looking successful.
+        cursor = params.delete(:_next) || params.delete(:next)
+        seen = {}
+
+        loop do
+          page_params = cursor ? params.merge(_next: cursor) : params
+          data, _status, headers = fetch_page.call(page_params)
+          Array(data).each { |item| yielder << item }
+
+          cursor = next_cursor(headers)
+          break if cursor.nil?
+          # A server that returns a cursor it already gave us would loop forever.
+          break if seen[cursor]
+
+          seen[cursor] = true
+        end
+      end
+    end
+  end
+end

data/lib/flat_api/retry.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'flat_api/errors'
+
+# Retry policy for the Flat API.
+#
+# Flat does not follow the usual conventions, and getting this wrong is silent:
+#   * rate limiting returns 403, not 429
+#   * there is no Retry-After header; the reset is X-RateLimit-Reset, UTC epoch seconds
+#   * a plain 403 is a genuine authorization failure and must never be retried
+module FlatApi
+  # Methods safe to replay. A non-idempotent request that may already have been applied is not.
+  IDEMPOTENT_METHODS = %w[GET HEAD OPTIONS PUT DELETE].freeze
+  MAX_RATE_LIMIT_WAIT = 300.0
+
+  class RetryPolicy
+    attr_reader :attempts, :backoff_base, :backoff_max, :jitter, :respect_rate_limit_reset
+
+    def initialize(attempts: 3, backoff_base: 0.5, backoff_max: 30.0, jitter: 0.25,
+                   respect_rate_limit_reset: true)
+      @attempts = attempts
+      @backoff_base = backoff_base
+      @backoff_max = backoff_max
+      @jitter = jitter
+      @respect_rate_limit_reset = respect_rate_limit_reset
+    end
+
+    # No retries. Errors still arrive typed, and a rate-limit error still carries its reset.
+    def self.disabled
+      new(attempts: 1)
+    end
+
+    def enabled?
+      attempts > 1
+    end
+
+    def should_retry?(error, method, attempt)
+      return false if attempt >= attempts
+      return false unless IDEMPOTENT_METHODS.include?(method.to_s.upcase)
+      return true if error.is_a?(FlatRateLimitError)
+      return true if error.is_a?(FlatServerError)
+
+      # A transport failure before the request was sent is safe to replay.
+      error.is_a?(IOError) || error.is_a?(SystemCallError)
+    end
+
+    def delay_for(error, attempt)
+      if respect_rate_limit_reset && error.is_a?(FlatRateLimitError) && error.reset
+        wait = error.reset - Time.now.to_i
+        return [wait + rand * jitter, MAX_RATE_LIMIT_WAIT].min if wait.positive?
+      end
+      exponential = [backoff_base * (2**(attempt - 1)), backoff_max].min
+      exponential + (rand * jitter * exponential)
+    end
+  end
+end

data/lib/flat_api/version.rb

@@ -1,15 +1,15 @@
 =begin
 #Flat API
 
-#The Flat API allows you to easily extend the abilities of the [Flat Platform](https://flat.io), with a wide range of use cases including the following:  * Creating and importing new music scores using MusicXML or MIDI files * Browsing, updating, copying, exporting the user's scores (for example in MP3, WAV or MIDI) * Managing educational resources with Flat for Education: creating & updating the organization accounts, the classes, rosters and assignments.  The Flat API is built on HTTP. Our API is RESTful It has predictable resource URLs. It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body. The [schema](/swagger.yaml) of this API follows the [OpenAPI Initiative (OAI) specification](https://www.openapis.org/), you can use and work with [compatible Swagger tools](http://swagger.io/open-source-integrations/). This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with [W3C spec](https://www.w3.org/TR/cors/).  You can use your favorite HTTP/REST library for your programming language to use Flat's API. This specification and reference is [available on Github](https://github.com/FlatIO/api-reference).  Getting Started and learn more:  * [API Overview and interoduction](https://flat.io/developers/docs/api/) * [Authentication (Personal Access Tokens or OAuth2)](https://flat.io/developers/docs/api/authentication.html) * [SDKs](https://flat.io/developers/docs/api/sdks.html) * [Rate Limits](https://flat.io/developers/docs/api/rate-limits.html) * [Changelog](https://flat.io/developers/docs/api/changelog.html) 
+#The Flat API allows you to easily extend the abilities of the [Flat Platform](https://flat.io), with a wide range of use cases including the following:  * Creating and importing new music scores using MusicXML, MIDI, Guitar Pro, MuseScore, ABC notation, and many other formats * Browsing, updating, copying, exporting the user's scores (for example in MP3, WAV or MIDI) * Managing educational resources with Flat for Education: creating & updating the organization accounts, the classes, rosters and assignments.  The Flat API is built on HTTP. Our API is RESTful It has predictable resource URLs. It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body. The [schema](/swagger.yaml) of this API follows the [OpenAPI Initiative (OAI) specification](https://www.openapis.org/), you can use and work with [compatible Swagger tools](http://swagger.io/open-source-integrations/). This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with [W3C spec](https://www.w3.org/TR/cors/).  You can use your favorite HTTP/REST library for your programming language to use Flat's API. This specification and reference is [available on Github](https://github.com/FlatIO/api-reference).  Getting Started and learn more:  * [API Overview and introduction](https://flat.io/developers/docs/api/) * [Authentication (Personal Access Tokens or OAuth2)](https://flat.io/developers/docs/api/authentication.html) * [SDKs](https://flat.io/developers/docs/api/sdks.html) * [Rate Limits](https://flat.io/developers/docs/api/rate-limits.html) * [Changelog](https://flat.io/developers/docs/api/changelog.html) 
 
-OpenAPI spec version: 2.6.0
+The version of the OpenAPI document: 2.26.1
 Contact: developers@flat.io
-Generated by: https://github.com/swagger-api/swagger-codegen.git
-Swagger Codegen version: 2.4.0-SNAPSHOT
+Generated by: https://openapi-generator.tech
+Generator version: 7.24.0
 
 =end
 
 module FlatApi
-  VERSION = "0.2.0"
+  VERSION = '1.0.0'
 end