assinafy 1.5.0

data/lib/assinafy/resources/auth_resource.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Assinafy
+  module Resources
+    # Authentication and API key management.
+    #
+    # See https://api.assinafy.com.br/v1/docs#authentication for the full
+    # documentation of these endpoints.
+    class AuthResource < BaseResource
+      # Authenticate with email and password.
+      #
+      # The returned `access_token` is a JWT that typically expires in one hour. For long-lived
+      # back-end integrations, prefer an API key (see #create_api_key) over the access token.
+      #
+      # @param email    [String]
+      # @param password [String]
+      # @return [Hash] unwrapped payload: { "access_token" => String, "user" => Hash, "accounts" => Array<Hash> }
+      # @raise [Assinafy::ApiError] on a non-2xx response
+      #
+      # @see POST /login
+      #
+      # @example Request and response
+      #   resource.login(email: 'user@example.com', password: 'secret')
+      #   # Request body sent by the SDK:
+      #   #   { "email": "user@example.com", "password": "secret" }
+      #   #
+      #   # Returns the unwrapped data payload (envelope { status, message, data } stripped):
+      #   # {
+      #   #   "access_token" => "access-token-placeholder",
+      #   #   "user" => {
+      #   #     "id" => "user-id", "name" => "Example User",
+      #   #     "email" => "user@example.com", "telephone" => "+15555550100",
+      #   #     "government_id" => "00000000000", "is_email_verified" => false,
+      #   #     "has_accepted_terms" => true, "created_at" => "2023-03-03T11:51:34Z",
+      #   #     "to_be_deleted_at" => nil
+      #   #   },
+      #   #   "accounts" => [
+      #   #     { "id" => "account-id", "name" => "Example Workspace", "roles" => ["owner"],
+      #   #       "is_delete_allowed" => true, "created_at" => "2023-03-03T11:51:34Z" }
+      #   #   ]
+      #   # }
+      def login(email:, password:)
+        call('Failed to login') do
+          @connection.post('login', body_params(email: email, password: password))
+        end
+      end
+
+      # Authenticate with a third-party identity provider token.
+      #
+      # Currently the only supported provider is `google`. Returns the same shape as #login.
+      #
+      # @param provider           [String] the provider type; currently only `google`
+      # @param token              [String] provider-issued OAuth/OIDC access or ID token
+      # @param has_accepted_terms [Boolean]
+      # @return [Hash] unwrapped payload: { "access_token" => String, "user" => Hash, "accounts" => Array<Hash> }
+      #
+      # @see POST /authentication/social-login
+      #
+      # @example Request and response
+      #   resource.social_login(provider: 'google', token: 'provider-token', has_accepted_terms: true)
+      #   # Request body sent by the SDK:
+      #   #   { "provider": "google", "token": "provider-token", "has_accepted_terms": true }
+      #   #
+      #   # Returns the unwrapped data payload (envelope stripped); same shape as #login:
+      #   # {
+      #   #   "access_token" => "access-token-placeholder",
+      #   #   "user" => { "id" => "user-id", "name" => "Example User", ... },
+      #   #   "accounts" => [
+      #   #     { "id" => "account-id", "name" => "Example Workspace", "roles" => ["owner"],
+      #   #       "is_delete_allowed" => true, "created_at" => "2023-03-03T11:51:34Z" }
+      #   #   ]
+      #   # }
+      def social_login(provider:, token:, has_accepted_terms:)
+        call('Failed to login with social provider') do
+          @connection.post(
+            'authentication/social-login',
+            body_params(
+              provider:           provider,
+              token:              token,
+              has_accepted_terms: has_accepted_terms
+            )
+          )
+        end
+      end
+
+      # Link a third-party identity provider to the authenticated user's account.
+      #
+      # @param provider [String] the provider type; currently only `google`
+      # @param token    [String] provider-issued OAuth/OIDC token
+      # @return [nil] the documented success envelope has no `data` payload
+      # @see POST /auth/link-social-login
+      # @example Link a Google account
+      #   client.auth.link_social_login(provider: 'google', token: 'provider-token')
+      #   # Request body sent by the SDK:
+      #   #   { "provider": "google", "token": "provider-token" }
+      #   # Response: { "status": 200, "message": "Provider linked" }
+      #   # => nil
+      def link_social_login(provider:, token:)
+        call('Failed to link social login') do
+          @connection.post('auth/link-social-login', body_params(provider: provider, token: token))
+        end
+      end
+
+      # Generate a new API key for the authenticated user.
+      #
+      # The returned key is shown in full only once, here; afterwards #get_api_key returns a masked
+      # version. IMPORTANT: generating a new key deletes (invalidates) the previous one. Send the key
+      # via the `X-Api-Key` header and never expose it in a front-end application.
+      #
+      # @param password [String] the user's current password
+      # @return [Hash] unwrapped payload: { "api_key" => String } (the new key, in full)
+      #
+      # @see POST /users/api-keys
+      #
+      # @example Request and response
+      #   resource.create_api_key(password: 'secret')
+      #   # Request body sent by the SDK:
+      #   #   { "password": "secret" }
+      #   #
+      #   # Returns the unwrapped data payload (envelope stripped):
+      #   # { "api_key" => "api-key-created-once" }
+      def create_api_key(password:)
+        call('Failed to create API key') do
+          @connection.post('users/api-keys', body_params(password: password))
+        end
+      end
+
+      # Retrieve the active API key for the authenticated user.
+      #
+      # For security the key is returned MASKED (only the last 4 characters are visible); the full key
+      # is only available once, at #create_api_key time. Returns `nil` if no key has been generated yet.
+      # This endpoint works with `X-Api-Key` authentication (verified live), not only a Bearer token.
+      #
+      # @return [Hash, nil] unwrapped payload: { "api_key" => String } (masked), or nil if no key exists yet
+      # @see GET /users/api-keys
+      #
+      # @example Request and response (key exists)
+      #   resource.get_api_key
+      #   # No request body (GET).
+      #   #
+      #   # Returns the unwrapped data payload (envelope stripped):
+      #   # { "api_key" => "************************************************************9Jdr" }
+      #
+      # @example Response when no key has been generated yet
+      #   resource.get_api_key # => nil
+      def get_api_key
+        call('Failed to get API key') do
+          @connection.get('users/api-keys')
+        end
+      end
+
+      alias api_key get_api_key
+
+      # Delete the API key of the authenticated user.
+      #
+      # The SDK ignores the response body and always returns `nil` on success. (The API itself
+      # responds with an empty `data` payload.)
+      #
+      # @return [nil]
+      # @see DELETE /users/api-keys
+      #
+      # @example Request and response
+      #   resource.delete_api_key
+      #   # No request body (DELETE).
+      #   #
+      #   # Returns nil on success (the API's empty `data` payload is discarded).
+      #   # => nil
+      def delete_api_key
+        call_void('Failed to delete API key') do
+          @connection.delete('users/api-keys')
+        end
+      end
+
+      # Change the authenticated user's password.
+      #
+      # @param email        [String]
+      # @param password     [String] current password
+      # @param new_password [String] the new password to set
+      # @return [Hash] unwrapped payload: { "email" => String }
+      #
+      # @see PUT /authentication/change-password
+      #
+      # @example Request and response
+      #   resource.change_password(email: 'user@example.com', password: 'current-password',
+      #                            new_password: 'new-password')
+      #   # Request body sent by the SDK:
+      #   #   { "email": "user@example.com", "password": "current-password",
+      #   #     "new_password": "new-password" }
+      #   #
+      #   # Returns the unwrapped data payload (envelope stripped):
+      #   # { "email" => "user@example.com" }
+      def change_password(email:, password:, new_password:)
+        call('Failed to change password') do
+          @connection.put(
+            'authentication/change-password',
+            body_params(email: email, password: password, new_password: new_password)
+          )
+        end
+      end
+
+      # Trigger a password-reset email for the given account.
+      #
+      # Used when the user forgot their password or has not set one yet. An email with a reset token
+      # is sent; pass that token to #reset_password to complete the flow.
+      #
+      # @param email [String]
+      # @return [Hash] unwrapped payload: { "email" => String }
+      #
+      # @see PUT /authentication/request-password-reset
+      #
+      # @example Request and response
+      #   resource.request_password_reset(email: 'user@example.com')
+      #   # Request body sent by the SDK:
+      #   #   { "email": "user@example.com" }
+      #   #
+      #   # Returns the unwrapped data payload (envelope stripped):
+      #   # { "email" => "user@example.com" }
+      def request_password_reset(email:)
+        call('Failed to request password reset') do
+          @connection.put('authentication/request-password-reset', body_params(email: email))
+        end
+      end
+
+      # Reset the password using the token sent via #request_password_reset.
+      #
+      # @param email        [String]
+      # @param new_password [String] the new password to set
+      # @param token        [String, nil] reset token from the email; omitted from the body when nil
+      # @return [Hash] unwrapped payload: { "email" => String }
+      #
+      # @see PUT /authentication/reset-password
+      #
+      # @example Request and response
+      #   resource.reset_password(email: 'user@example.com', new_password: 'new-password',
+      #                           token: 'reset-token')
+      #   # Request body sent by the SDK (nil token would be omitted by body_params):
+      #   #   { "email": "user@example.com", "token": "reset-token", "new_password": "new-password" }
+      #   #
+      #   # Returns the unwrapped data payload (envelope stripped):
+      #   # { "email" => "user@example.com" }
+      def reset_password(email:, new_password:, token: nil)
+        call('Failed to reset password') do
+          @connection.put(
+            'authentication/reset-password',
+            body_params(email: email, token: token, new_password: new_password)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/assinafy/resources/base_resource.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module Assinafy
+  module Resources
+    # Shared plumbing for every resource: a Faraday connection, an optional
+    # default account ID, parameter normalisation, response-envelope handling,
+    # pagination header parsing, and a single `request`/`call` pipeline that
+    # wraps Faraday and Assinafy errors into the SDK's own error hierarchy.
+    class BaseResource
+      PATH_SEGMENT = /\A[A-Za-z0-9._~-]+\z/
+      PAGINATION_HEADERS = {
+        current_page: 'x-pagination-current-page',
+        per_page:     'x-pagination-per-page',
+        total:        'x-pagination-total-count',
+        last_page:    'x-pagination-page-count'
+      }.freeze
+
+      # @param connection         [Faraday::Connection]
+      # @param default_account_id [String, nil] used by `account_id` when no override is passed
+      # @param logger             [Logger, nil]
+      def initialize(connection, default_account_id = nil, logger = nil)
+        @connection         = connection
+        @default_account_id = default_account_id
+        @logger             = logger || NullLogger.new
+      end
+
+      protected
+
+      def account_id(explicit = nil)
+        require_id(explicit.nil? ? @default_account_id : explicit, 'Account ID')
+      end
+
+      # Ensure a required scalar argument is present (not nil/blank).
+      # `require_id` is kept as an intention-revealing alias for path IDs.
+      def require_present(value, name)
+        return value unless value.nil? || value.to_s.strip.empty?
+
+        raise ValidationError.new("#{name} is required")
+      end
+
+      def require_id(value, name)
+        id = require_present(value, name)
+        raise ValidationError.new("#{name} must be a String") unless id.is_a?(String)
+
+        return id if PATH_SEGMENT.match?(id) && id != '.' && id != '..'
+
+        raise ValidationError.new("#{name} contains invalid characters")
+      end
+
+      def require_boolean(value, name)
+        return value if [true, false].include?(value)
+
+        raise ValidationError.new("#{name} must be true or false")
+      end
+
+      def require_payload(payload, name = 'Payload')
+        raise ValidationError.new("#{name} must be a Hash") unless payload.is_a?(Hash)
+
+        payload
+      end
+
+      def require_array(value, name)
+        return value if value.is_a?(Array) && !value.empty?
+
+        raise ValidationError.new("#{name} must be a non-empty Array")
+      end
+
+      def query_params(params)
+        Utils.query_params(params)
+      end
+
+      def body_params(params)
+        Utils.body_params(params)
+      end
+
+      # Normalise an upload source into `[buffer, file_name]`. Shared by every
+      # multipart upload endpoint (document upload, template create, account
+      # logo). Accepts a path String, or a Hash with `:file_path` (path) **or**
+      # `:buffer` + `:file_name` (raw bytes).
+      #
+      # @param source [String, Hash]
+      # @param max_bytes [Integer, nil] read at most one byte beyond this limit
+      # @return [Array(String, String)] `[buffer, file_name]`
+      # @raise [ValidationError] on an unusable source
+      def read_source(source, max_bytes: nil)
+        case source
+        when String
+          [read_file(source, max_bytes), File.basename(source)]
+        when Hash
+          if source[:buffer]
+            raise ValidationError.new('file_name is required when uploading a buffer') unless source[:file_name]
+
+            [source[:buffer], source[:file_name]]
+          elsif source[:file_path]
+            [read_file(source[:file_path], max_bytes), source[:file_name] || File.basename(source[:file_path])]
+          else
+            raise ValidationError.new('Invalid upload source: provide :file_path or :buffer')
+          end
+        else
+          raise ValidationError.new('Invalid upload source: provide a path String or a Hash with :file_path/:buffer')
+        end
+      rescue SystemCallError, ArgumentError, TypeError => e
+        raise ValidationError.new("Unable to read upload source: #{e.message}", { cause: e.class.name })
+      end
+
+      def read_file(path, max_bytes)
+        return File.binread(path) unless max_bytes
+
+        File.binread(path, max_bytes + 1)
+      end
+
+      # Wrap raw bytes in a Faraday::FilePart for a multipart request body.
+      #
+      # @param buffer       [String] raw file bytes
+      # @param file_name    [String]
+      # @param content_type [String] MIME type (defaults to sniffing the extension)
+      # @return [Faraday::FilePart]
+      def file_part(buffer, file_name, content_type = nil)
+        Faraday::FilePart.new(StringIO.new(buffer), content_type || mime_type_for(file_name), file_name)
+      end
+
+      def mime_type_for(file_name)
+        case File.extname(file_name.to_s).downcase
+        when '.pdf'         then 'application/pdf'
+        when '.png'         then 'image/png'
+        when '.jpg', '.jpeg' then 'image/jpeg'
+        when '.gif'         then 'image/gif'
+        when '.webp'        then 'image/webp'
+        when '.svg'         then 'image/svg+xml'
+        else 'application/octet-stream'
+        end
+      end
+
+      def http_get(path, params = {})
+        @connection.get(path, query_params(params))
+      end
+
+      def http_post(path, body = nil, params = {})
+        @connection.post(path) do |request|
+          request.params.update(query_params(params))
+          request.body = body unless body.nil?
+        end
+      end
+
+      def http_put(path, body = nil, params = {})
+        @connection.put(path) do |request|
+          request.params.update(query_params(params))
+          request.body = body unless body.nil?
+        end
+      end
+
+      def http_patch(path, body = nil, params = {})
+        @connection.patch(path) do |request|
+          request.params.update(query_params(params))
+          request.body = body unless body.nil?
+        end
+      end
+
+      def http_delete(path, params = {}, body: nil)
+        @connection.delete(path) do |request|
+          request.params.update(query_params(params))
+          request.body = body unless body.nil?
+        end
+      end
+
+      def call(label)
+        Utils.handle_assinafy_response(request(label) { yield }.body)
+      end
+
+      def call_optional(label)
+        call(label) { yield }
+      rescue ApiError => e
+        raise unless e.status_code == 404
+
+        nil
+      end
+
+      def call_void(label)
+        call(label) { yield }
+        nil
+      end
+
+      def call_binary(label)
+        body = request(label) { yield }.body
+        body = Utils.handle_assinafy_response(body) if body.is_a?(Hash)
+        return ''.b if body.nil?
+        return body.b if body.is_a?(String)
+
+        raise Assinafy::Error.new("#{label}: expected a binary response", { body_class: body.class.name })
+      end
+
+      def call_list(label)
+        response = request(label) { yield }
+        body     = Utils.handle_assinafy_response(response.body)
+        result   = { data: extract_list_data(body) }
+        meta     = parse_pagination_meta(response.headers)
+        result[:meta] = meta if meta
+        result
+      end
+
+      private
+
+      def request(label)
+        response = yield
+        check_status!(response, label)
+        response
+      rescue Faraday::ConnectionFailed, Faraday::TimeoutError, Faraday::SSLError => e
+        raise NetworkError.new("#{label}: #{e.message}", { cause: e.class.name })
+      rescue Assinafy::Error
+        raise
+      rescue StandardError => e
+        # Preserve the original class for debugging; Ruby keeps the original
+        # exception accessible via #cause since we re-raise inside the rescue.
+        raise Assinafy::Error.new("#{label}: #{e.message}", { cause: e.class.name })
+      end
+
+      def check_status!(response, _label)
+        return if (200..299).cover?(response.status)
+
+        raise ApiError.from_response(response.status, response.body)
+      end
+
+      def extract_list_data(body)
+        case body
+        when Array then body
+        when Hash  then body['data'] || []
+        else            []
+        end
+      end
+
+      def parse_pagination_meta(headers)
+        return nil unless headers
+
+        meta = PAGINATION_HEADERS.each_with_object({}) do |(key, header), acc|
+          value = to_int(headers[header])
+          acc[key] = value if value
+        end
+        meta.empty? ? nil : meta
+      end
+
+      def to_int(value)
+        return nil if value.nil?
+
+        Integer(value)
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+  end
+end