mintsoft 0.1.0

data/lib/mintsoft/auth_client.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/net_http"
+
+module Mintsoft
+  class AuthClient
+    BASE_URL = "https://api.mintsoft.com"
+
+    attr_reader :base_url, :conn_opts
+
+    def initialize(base_url: BASE_URL, conn_opts: {})
+      @base_url = base_url
+      @conn_opts = conn_opts
+    end
+
+    def connection
+      @connection ||= Faraday.new do |conn|
+        conn.url_prefix = @base_url
+        conn.options.merge!(@conn_opts)
+        conn.request :json
+        conn.response :json, content_type: "application/json"
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def auth
+      @auth ||= AuthResource.new(self)
+    end
+
+    private
+
+    class AuthResource
+      def initialize(client)
+        @client = client
+      end
+
+      def authenticate(username, password)
+        validate_credentials!(username, password)
+
+        response = @client.connection.post("/api/auth") do |req|
+          req.body = {
+            username: username,
+            password: password
+          }
+        end
+
+        if response.success?
+          handle_success_response(response.body)
+        else
+          handle_error_response(response)
+        end
+      end
+
+      private
+
+      def validate_credentials!(username, password)
+        raise ValidationError, "Username required" if username.nil? || username.empty?
+        raise ValidationError, "Password required" if password.nil? || password.empty?
+      end
+
+      def handle_success_response(body)
+        token = body.dig("token") || body.dig("access_token") || body.dig("Token")
+        raise APIError, "No token found in response" unless token
+
+        AuthResponse.new(body.merge("token" => token))
+      end
+
+      def handle_error_response(response)
+        case response.status
+        when 401
+          raise AuthenticationError, "Invalid credentials"
+        when 400
+          raise ValidationError, "Invalid request: #{extract_error_message(response.body)}"
+        else
+          raise APIError, "Authentication failed: #{response.status} - #{extract_error_message(response.body)}"
+        end
+      end
+
+      def extract_error_message(body)
+        return body if body.is_a?(String)
+        return body["error"] || body["message"] || body.to_s if body.is_a?(Hash)
+
+        "Unknown error"
+      end
+    end
+
+    class AuthResponse < Base
+      def token
+        super || access_token || Token
+      end
+
+      def expires_at
+        return nil unless expires_in
+
+        Time.now + expires_in.to_i
+      end
+
+      def expired?
+        expires_at && Time.now >= expires_at
+      end
+    end
+  end
+end

data/lib/mintsoft/base.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/string"
+require "ostruct"
+
+module Mintsoft
+  class Base < OpenStruct
+    def initialize(attributes)
+      super to_ostruct(attributes)
+    end
+
+    def to_ostruct(obj)
+      if obj.is_a?(Hash)
+        OpenStruct.new(obj.transform_keys { |key| key.to_s.underscore }.transform_values { |val| to_ostruct(val) })
+      elsif obj.is_a?(Array)
+        obj.map { |o| to_ostruct(o) }
+      else # Assumed to be a primitive value
+        obj
+      end
+    end
+
+    # Convert back to hash without table key, including nested structures
+    def to_hash
+      ostruct_to_hash(self)
+    end
+
+    private
+
+    def ostruct_to_hash(object)
+      case object
+      when OpenStruct
+        hash = object.to_h.reject { |k, _| k == :table }
+        hash.transform_keys(&:to_s).transform_values { |value| ostruct_to_hash(value) }
+      when Array
+        object.map { |item| ostruct_to_hash(item) }
+      when Hash
+        object.transform_keys(&:to_s).transform_values { |value| ostruct_to_hash(value) }
+      else
+        object
+      end
+    end
+  end
+end

data/lib/mintsoft/client.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/net_http"
+
+module Mintsoft
+  class Client
+    BASE_URL = "https://api.mintsoft.com"
+
+    attr_reader :token, :base_url, :conn_opts
+
+    def initialize(token:, base_url: BASE_URL, conn_opts: {})
+      @token = token
+      @base_url = base_url
+      @conn_opts = conn_opts
+    end
+
+    def connection
+      @connection ||= Faraday.new do |conn|
+        conn.url_prefix = @base_url
+        conn.options.merge!(@conn_opts)
+        conn.request :authorization, :Bearer, @token
+        conn.request :json
+        conn.response :json, content_type: "application/json"
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def orders
+      @orders ||= Resources::Orders.new(self)
+    end
+
+    def returns
+      @returns ||= Resources::Returns.new(self)
+    end
+  end
+end

data/lib/mintsoft/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Mintsoft
+  class Error < StandardError; end
+  class APIError < Error; end
+  class AuthenticationError < APIError; end
+  class NotFoundError < APIError; end
+  class ValidationError < APIError; end
+end

data/lib/mintsoft/objects/order.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Mintsoft
+  module Objects
+    class Order < Base
+      # Convenience methods for common API response formats
+      def order_id
+        id || order_id
+      end
+
+      def order_ref
+        order_number || order_reference || ref
+      end
+    end
+  end
+end

data/lib/mintsoft/objects/return.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mintsoft
+  module Objects
+    class Return < Base
+      # Access nested items as OpenStruct objects
+      def items
+        return_items || items_array || []
+      end
+
+      def items_count
+        items.length
+      end
+
+      # Access item properties through OpenStruct
+      def item_quantities
+        items.map(&:quantity).sum
+      end
+
+      # Convenience methods for common API response formats
+      def return_id
+        id || return_id
+      end
+    end
+  end
+end

data/lib/mintsoft/objects/return_reason.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Mintsoft
+  module Objects
+    class ReturnReason < Base
+      def active?
+        active == true
+      end
+    end
+  end
+end

data/lib/mintsoft/resources/base_resource.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Mintsoft
+  module Resources
+    class BaseResource
+      def initialize(client)
+        @client = client
+      end
+
+      protected
+
+      def get_request(url, params: {})
+        @client.connection.get(url) do |req|
+          req.params.merge!(params) unless params.empty?
+        end
+      end
+
+      def post_request(url, body: {})
+        @client.connection.post(url) do |req|
+          req.body = body unless body.empty?
+        end
+      end
+
+      def handle_response(response)
+        if response.success?
+          response.body
+        else
+          handle_error(response)
+        end
+      end
+
+      def handle_error(response)
+        case response.status
+        when 401
+          raise AuthenticationError, "Invalid or expired token"
+        when 400
+          raise ValidationError, "Invalid request data: #{extract_error_message(response.body)}"
+        when 404
+          raise NotFoundError, "Resource not found"
+        else
+          raise APIError, "API error: #{response.status} - #{extract_error_message(response.body)}"
+        end
+      end
+
+      def extract_error_message(body)
+        return body if body.is_a?(String)
+        return body["error"] || body["message"] || body.to_s if body.is_a?(Hash)
+
+        "Unknown error"
+      end
+    end
+  end
+end

data/lib/mintsoft/resources/orders.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Mintsoft
+  module Resources
+    class Orders < BaseResource
+      def search(order_number)
+        validate_order_number!(order_number)
+
+        response = get_request("/api/Order/Search", params: {"OrderNumber" => order_number})
+
+        if response.success?
+          parse_orders(response.body)
+        else
+          case response.status
+          when 404
+            [] # Return empty array for not found
+          else
+            handle_error(response)
+          end
+        end
+      end
+
+      private
+
+      def validate_order_number!(order_number)
+        raise ValidationError, "Order number required" if order_number.nil? || order_number.empty?
+      end
+
+      def parse_orders(data)
+        return [] unless data.is_a?(Array)
+
+        data.map { |order_data| Objects::Order.new(order_data) }
+      end
+    end
+  end
+end

data/lib/mintsoft/resources/returns.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Mintsoft
+  module Resources
+    class Returns < BaseResource
+      def reasons
+        response = get_request("/api/Return/Reasons")
+
+        if response.success?
+          parse_reasons(response.body)
+        else
+          handle_error(response)
+        end
+      end
+
+      def create(order_id)
+        validate_order_id!(order_id)
+
+        response = post_request("/api/Return/CreateReturn/#{order_id}")
+
+        if response.success?
+          # Extract return ID from ToolkitResult and create Return object
+          return_id = extract_return_id(response.body)
+          Objects::Return.new({
+            "id" => return_id,
+            "order_id" => order_id,
+            "status" => "pending"
+          })
+        else
+          handle_error(response)
+        end
+      end
+
+      def add_item(return_id, item_attributes)
+        validate_return_id!(return_id)
+        validate_item_attributes!(item_attributes)
+
+        payload = format_item_payload(item_attributes)
+        response = post_request("/api/Return/#{return_id}/AddItem", body: payload)
+
+        if response.success?
+          true # Simple success indicator
+        else
+          handle_error(response)
+        end
+      end
+
+      private
+
+      def validate_order_id!(order_id)
+        raise ValidationError, "Order ID required" unless order_id&.to_i&.positive?
+      end
+
+      def validate_return_id!(return_id)
+        raise ValidationError, "Return ID required" unless return_id&.to_i&.positive?
+      end
+
+      def validate_item_attributes!(attrs)
+        required = [:product_id, :quantity, :reason_id]
+        required.each do |field|
+          raise ValidationError, "#{field} required" unless attrs[field]
+        end
+        raise ValidationError, "Quantity must be positive" unless attrs[:quantity].to_i > 0
+      end
+
+      def parse_reasons(data)
+        return [] unless data.is_a?(Array)
+
+        data.map { |reason_data| Objects::ReturnReason.new(reason_data) }
+      end
+
+      def extract_return_id(toolkit_result)
+        # Parse ToolkitResult to extract return ID - handles various response formats
+        toolkit_result.dig("result", "return_id") ||
+        toolkit_result.dig("data", "id") ||
+        toolkit_result["id"]
+      end
+
+      def format_item_payload(attrs)
+        {
+          "ProductId" => attrs[:product_id],
+          "Quantity" => attrs[:quantity],
+          "ReasonId" => attrs[:reason_id],
+          "UnitValue" => attrs[:unit_value],
+          "Notes" => attrs[:notes]
+        }.compact
+      end
+    end
+  end
+end

data/lib/mintsoft/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Mintsoft
+  VERSION = "0.1.0"
+end

data/lib/mintsoft.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "mintsoft/version"
+require_relative "mintsoft/errors"
+require_relative "mintsoft/base"
+require_relative "mintsoft/auth_client"
+require_relative "mintsoft/client"
+require_relative "mintsoft/resources/base_resource"
+require_relative "mintsoft/resources/orders"
+require_relative "mintsoft/resources/returns"
+require_relative "mintsoft/objects/order"
+require_relative "mintsoft/objects/return"
+require_relative "mintsoft/objects/return_reason"
+
+module Mintsoft
+  # Main entry point for the Mintsoft API wrapper
+end

data/sig/mintsoft.rbs

@@ -0,0 +1,4 @@
+module Mintsoft
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,161 @@
+--- !ruby/object:Gem::Specification
+name: mintsoft
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andy Chong
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-net_http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: A Ruby gem for interacting with the Mintsoft API
+email:
+- andygg1996personal@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".serena/memories/code_style_conventions.md"
+- ".serena/memories/codebase_structure.md"
+- ".serena/memories/development_environment.md"
+- ".serena/memories/project_overview.md"
+- ".serena/memories/suggested_commands.md"
+- ".serena/memories/task_completion_checklist.md"
+- ".serena/project.yml"
+- ".standard.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- claudedocs/AUTH_CLIENT_DESIGN.md
+- claudedocs/FINAL_SIMPLIFIED_DESIGN.md
+- claudedocs/IMPLEMENTATION_SUMMARY.md
+- claudedocs/INDEX.md
+- claudedocs/MINIMAL_IMPLEMENTATION_PLAN.md
+- claudedocs/TOKEN_ONLY_CLIENT_DESIGN.md
+- claudedocs/USAGE_EXAMPLES.md
+- examples/complete_workflow.rb
+- lib/mintsoft.rb
+- lib/mintsoft/auth_client.rb
+- lib/mintsoft/base.rb
+- lib/mintsoft/client.rb
+- lib/mintsoft/errors.rb
+- lib/mintsoft/objects/order.rb
+- lib/mintsoft/objects/return.rb
+- lib/mintsoft/objects/return_reason.rb
+- lib/mintsoft/resources/base_resource.rb
+- lib/mintsoft/resources/orders.rb
+- lib/mintsoft/resources/returns.rb
+- lib/mintsoft/version.rb
+- sig/mintsoft.rbs
+homepage: https://github.com/Postco/mintsoft
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Postco/mintsoft
+  source_code_uri: https://github.com/Postco/mintsoft
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: Mintsoft API Wrapper
+test_files: []