mintsoft 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d4e347c511df39663a170a502c452dc78cfe870b6015d197f1720bf8c36616e
-  data.tar.gz: d0da7297752a5f056353dae41fb898f91cb8a8b621c3fc43536a998156ab5918
+  metadata.gz: f77c74116b807d8a07ce73ccf258237db3665585ede056cc00d08044fe811497
+  data.tar.gz: 06e3a80cc0b9e2f38424116875c5e96fd0a78d78dfb7fb8c3330824e3fdf2600
 SHA512:
-  metadata.gz: ba56fd482853bbcbc970069a86ea43c6285733d2e21572176e7ae5ad2cc61919c3a9ac01f8e93f79a2092257966905ab4aa72b6804e9ffe04bab5c5f5ccea783
-  data.tar.gz: 831997f21475cccf9555d7cbe3604ae65e20a6828bea8cae8adfedc7d65c03cf5eb9a307cc9d47a07eb1b9b26006aa60d425faf060b130d7921960ed43094e70
+  metadata.gz: 4a443a1a412560f0dd8f97fd00a2aacbc2dc1ce3186bf5e59cf67e4dfb968661db32dda6fa2dc0591e8032fb696da461348b68c7c474471c53c5a1e2c90d8cab
+  data.tar.gz: 01a64e1ec0b9415434f6dcc3ba9f36f98d0e97121e1ef9b2cf301862053f5e2a086ba8b4d3d2c9ba75c855c78d2400435a57b8342070a26810461d3353b894e0

data/README.md

@@ -35,10 +35,10 @@ require 'mintsoft'
 
 # Step 1: Get authentication token
 auth_client = Mintsoft::AuthClient.new
-auth_response = auth_client.auth.authenticate("username", "password")
+token = auth_client.auth.authenticate("username", "password")
 
 # Step 2: Initialize client with token
-client = Mintsoft::Client.new(token: auth_response.token)
+client = Mintsoft::Client.new(token: token)
 
 # Step 3: Search for orders
 orders = client.orders.search("ORD-2024-001")
@@ -46,13 +46,13 @@ order = orders.first
 
 # Step 4: Get return reasons
 reasons = client.returns.reasons
-damage_reason = reasons.find { |r| r.name.include?("Damage") }
+damage_reason = reasons.find { |r| r.name.include?("Damaged") && r.active? }
 
 # Step 5: Create return
 return_obj = client.returns.create(order.id)
 
 # Step 6: Add item to return
-success = client.returns.add_item(return_obj.id, {
+result = client.returns.add_item(return_obj.id, {
   product_id: 123,
   quantity: 2,
   reason_id: damage_reason.id,
@@ -70,10 +70,8 @@ success = client.returns.add_item(return_obj.id, {
 auth_client = Mintsoft::AuthClient.new
 
 # Authenticate and get token
-auth_response = auth_client.auth.authenticate("username", "password")
-puts auth_response.token
-puts auth_response.expires_at
-puts auth_response.expired?
+token = auth_client.auth.authenticate("username", "password")
+puts token  # Direct token string
 ```
 
 #### Client
@@ -97,9 +95,10 @@ orders = client.orders.search("ORD-123")
 
 # Access order properties
 order = orders.first
-puts order.id
-puts order.order_number
-puts order.customer_id
+puts order.id              # Direct access to order ID
+puts order.order_number    # Direct access to order number
+puts order.customer_id     # Direct access to customer ID
+puts order.items&.length || 0  # Get number of items if available
 ```
 
 #### Returns
@@ -113,38 +112,86 @@ active_reasons = reasons.select(&:active?)
 return_obj = client.returns.create(order_id)
 
 # Add item to return
-client.returns.add_item(return_id, {
+result = client.returns.add_item(return_obj.id, {
   product_id: 123,
   quantity: 2,
   reason_id: reason_id,
   unit_value: 25.00,
   notes: "Optional notes"
 })
+
+# Access return properties
+puts return_obj.id          # Direct access to return ID
+puts return_obj.order_id    # Access to associated order ID (injected by resource)
+# Note: Items data structure depends on API response format
 ```
 
 ### Error Handling
 
+All error classes now include response context and status codes for better debugging:
+
 ```ruby
 begin
   orders = client.orders.search("ORD-123")
 rescue Mintsoft::AuthenticationError => e
-  # Token expired or invalid
+  # Token expired or invalid (401)
   puts "Authentication failed: #{e.message}"
+  puts "Status: #{e.status_code}"
 rescue Mintsoft::ValidationError => e
-  # Invalid request data
+  # Invalid request data (400)
   puts "Validation error: #{e.message}"
+  puts "Response: #{e.response.body if e.response}"
 rescue Mintsoft::NotFoundError => e
-  # Resource not found
+  # Resource not found (404)
   puts "Not found: #{e.message}"
 rescue Mintsoft::APIError => e
   # General API error
   puts "API error: #{e.message}"
+  puts "Status: #{e.status_code}"
 end
 ```
 
-### Complete Example
+### Object Methods
+
+#### Order Objects
+
+```ruby
+order = orders.first
+
+# Direct property access
+order.id            # Order ID
+order.order_number  # Order number
+order.customer_id   # Customer ID
+order.to_hash       # Convert to hash
+order.raw           # Original API response
+```
+
+#### Return Objects
+
+```ruby
+return_obj = client.returns.create(order_id)
+
+# Direct property access
+return_obj.id        # Return ID from API response
+return_obj.order_id  # Associated order ID (injected by resource)
+# Note: Other properties depend on API response structure
+```
+
+### Authentication Token Management
 
-See [examples/complete_workflow.rb](examples/complete_workflow.rb) for a full working example.
+The authentication method returns the token string directly:
+
+```ruby
+token = auth_client.auth.authenticate("username", "password")
+puts token  # Direct token string
+
+# Token management in workflow
+client = Mintsoft::Client.new(token: token)
+
+# For re-authentication when token expires:
+token = auth_client.auth.authenticate("username", "password") 
+client = Mintsoft::Client.new(token: token)
+```
 
 ## Development
 

data/examples/complete_workflow.rb

@@ -10,15 +10,13 @@ require "mintsoft"
 puts "=== Step 1: Authentication ==="
 auth_client = Mintsoft::AuthClient.new
 begin
-  auth_response = auth_client.auth.authenticate(
+  token = auth_client.auth.authenticate(
     ENV.fetch("MINTSOFT_USERNAME"),
     ENV.fetch("MINTSOFT_PASSWORD")
   )
-  
+
   puts "✅ Authentication successful!"
-  puts "Token: #{auth_response.token[0...10]}..."
-  puts "Expires at: #{auth_response.expires_at}"
-  puts "Expired?: #{auth_response.expired?}"
+  puts "Token: #{token[0...10]}..."
 rescue Mintsoft::AuthenticationError => e
   puts "❌ Authentication failed: #{e.message}"
   exit 1
@@ -30,7 +28,7 @@ end
 
 # Step 2: Initialize client with token
 puts "\n=== Step 2: Initialize Client ==="
-client = Mintsoft::Client.new(token: auth_response.token)
+client = Mintsoft::Client.new(token: token)
 puts "✅ Client initialized with token"
 
 # Step 3: Search for orders
@@ -38,20 +36,19 @@ puts "\n=== Step 3: Search Orders ==="
 order_number = "ORD-2024-001" # Change this to a real order number in your system
 begin
   orders = client.orders.search(order_number)
-  
+
   if orders.empty?
     puts "⚠️  No orders found with number: #{order_number}"
     puts "Please try with a different order number"
     exit 1
   end
-  
+
   order = orders.first
   puts "✅ Found #{orders.size} order(s)"
   puts "Order ID: #{order.id}"
   puts "Order Number: #{order.order_number}"
   puts "Customer ID: #{order.customer_id}" if order.respond_to?(:customer_id)
   puts "Status: #{order.status}" if order.respond_to?(:status)
-  
 rescue Mintsoft::ValidationError => e
   puts "❌ Validation error: #{e.message}"
   exit 1
@@ -69,21 +66,20 @@ puts "\n=== Step 4: Get Return Reasons ==="
 begin
   reasons = client.returns.reasons
   puts "✅ Found #{reasons.size} return reason(s)"
-  
+
   reasons.each do |reason|
     status = reason.active? ? "✅" : "❌"
     puts "  #{status} #{reason.name} (ID: #{reason.id}): #{reason.description}"
   end
-  
+
   # Select the first active reason for demo
   selected_reason = reasons.find(&:active?)
   if selected_reason.nil?
     puts "❌ No active return reasons found"
     exit 1
   end
-  
+
   puts "\n🎯 Selected reason: #{selected_reason.name}"
-  
 rescue Mintsoft::APIError => e
   puts "❌ API error: #{e.message}"
   exit 1
@@ -97,7 +93,6 @@ begin
   puts "Return ID: #{return_obj.id}"
   puts "Order ID: #{return_obj.order_id}"
   puts "Status: #{return_obj.status}"
-  
 rescue Mintsoft::ValidationError => e
   puts "❌ Validation error: #{e.message}"
   exit 1
@@ -118,7 +113,7 @@ item_attributes = {
 
 begin
   success = client.returns.add_item(return_obj.id, item_attributes)
-  
+
   if success
     puts "✅ Item added to return successfully!"
     puts "Product ID: #{item_attributes[:product_id]}"
@@ -129,7 +124,6 @@ begin
   else
     puts "❌ Failed to add item to return"
   end
-  
 rescue Mintsoft::ValidationError => e
   puts "❌ Validation error: #{e.message}"
 rescue Mintsoft::APIError => e
@@ -143,4 +137,4 @@ puts "   2. ✅ Initialized client"
 puts "   3. ✅ Searched for orders"
 puts "   4. ✅ Retrieved return reasons"
 puts "   5. ✅ Created return"
-puts "   6. ✅ Added item to return"
+puts "   6. ✅ Added item to return"

data/lib/mintsoft/auth_client.rb

@@ -5,7 +5,7 @@ require "faraday/net_http"
 
 module Mintsoft
   class AuthClient
-    BASE_URL = "https://api.mintsoft.com"
+    BASE_URL = "https://api.mintsoft.co.uk"
 
     attr_reader :base_url, :conn_opts
 
@@ -19,7 +19,7 @@ module Mintsoft
         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
@@ -46,7 +46,12 @@ module Mintsoft
         end
 
         if response.success?
-          handle_success_response(response.body)
+          # the response body is like "\"xxxx-xx-xxxx\""
+          if response.body.start_with?('"') && response.body.end_with?('"')
+            response.body.gsub(/^["']|["']$/, "")
+          else
+            response.body
+          end
         else
           handle_error_response(response)
         end
@@ -59,13 +64,6 @@ module Mintsoft
         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
@@ -84,21 +82,5 @@ module Mintsoft
         "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
+end

data/lib/mintsoft/base.rb

@@ -10,7 +10,7 @@ module Mintsoft
 
     def initialize(attributes)
       @original_response = deep_freeze_object(attributes)
-      super to_ostruct(attributes)
+      super(to_ostruct(attributes))
     end
 
     def to_ostruct(obj)
@@ -23,11 +23,16 @@ module Mintsoft
       end
     end
 
-    # Convert back to hash without table key, including nested structures
+    # Convert back to hash representation
     def to_hash
       ostruct_to_hash(self)
     end
 
+    # Get the raw original response data
+    def raw
+      @original_response
+    end
+
     private
 
     def deep_freeze_object(obj)
@@ -44,7 +49,7 @@ module Mintsoft
     def ostruct_to_hash(object)
       case object
       when OpenStruct
-        hash = object.to_h.reject { |k, _| k == :table }
+        hash = object.to_h.except(:table)
         hash.transform_keys(&:to_s).transform_values { |value| ostruct_to_hash(value) }
       when Array
         object.map { |item| ostruct_to_hash(item) }
@@ -55,4 +60,4 @@ module Mintsoft
       end
     end
   end
-end
+end

data/lib/mintsoft/client.rb

@@ -5,7 +5,7 @@ require "faraday/net_http"
 
 module Mintsoft
   class Client
-    BASE_URL = "https://api.mintsoft.com"
+    BASE_URL = "https://api.mintsoft.co.uk"
 
     attr_reader :token, :base_url, :conn_opts
 
@@ -16,14 +16,7 @@ module Mintsoft
     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
+      @connection ||= build_connection
     end
 
     def orders
@@ -33,5 +26,22 @@ module Mintsoft
     def returns
       @returns ||= Resources::Returns.new(self)
     end
+
+    private
+
+    def build_connection
+      Faraday.new do |conn|
+        conn.url_prefix = @base_url
+        conn.options.merge!(@conn_opts)
+        configure_middleware(conn)
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def configure_middleware(conn)
+      conn.headers["ms-apikey"] = @token
+      conn.request :json
+      conn.response :json, content_type: "application/json"
+    end
   end
-end
+end

data/lib/mintsoft/errors.rb

@@ -1,9 +1,26 @@
 # frozen_string_literal: true
 
 module Mintsoft
-  class Error < StandardError; end
+  # Base error class for all Mintsoft-related errors
+  class Error < StandardError
+    attr_reader :response, :status_code
+
+    def initialize(message = nil, response: nil, status_code: nil)
+      super(message)
+      @response = response
+      @status_code = status_code
+    end
+  end
+
+  # General API-related errors
   class APIError < Error; end
+
+  # Authentication and authorization errors
   class AuthenticationError < APIError; end
+
+  # Resource not found errors
   class NotFoundError < APIError; end
+
+  # Request validation errors
   class ValidationError < APIError; end
-end
+end

data/lib/mintsoft/objects/order.rb

@@ -3,14 +3,6 @@
 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
+end

data/lib/mintsoft/objects/return.rb

@@ -3,24 +3,6 @@
 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
+end

data/lib/mintsoft/objects/return_reason.rb

@@ -8,4 +8,4 @@ module Mintsoft
       end
     end
   end
-end
+end

data/lib/mintsoft/resources/base_resource.rb

@@ -22,7 +22,8 @@ module Mintsoft
       end
 
       def handle_response(response)
-        if response.success?
+        case response.status
+        when 200..299
           response.body
         else
           handle_error(response)
@@ -30,24 +31,44 @@ module Mintsoft
       end
 
       def handle_error(response)
-        case response.status
+        error_message = extract_error_message(response.body)
+
+        error_class = case response.status
+        when 400 then ValidationError
+        when 401 then AuthenticationError
+        when 404 then NotFoundError
+        else APIError
+        end
+
+        message = build_error_message(response.status, error_message)
+        raise error_class.new(message, response: response, status_code: response.status)
+      end
+
+      def build_error_message(status, error_message)
+        case status
         when 401
-          raise AuthenticationError, "Invalid or expired token"
+          "Invalid or expired token"
         when 400
-          raise ValidationError, "Invalid request data: #{extract_error_message(response.body)}"
+          "Invalid request data: #{error_message}"
         when 404
-          raise NotFoundError, "Resource not found"
+          "Resource not found"
         else
-          raise APIError, "API error: #{response.status} - #{extract_error_message(response.body)}"
+          "API error: #{status} - #{error_message}"
         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)
+      private
 
-        "Unknown error"
+      def extract_error_message(body)
+        case body
+        when String
+          body
+        when Hash
+          body["error"] || body["message"] || body.to_s
+        else
+          "Unknown error"
+        end
       end
     end
   end
-end
+end

data/lib/mintsoft/resources/orders.rb

@@ -5,18 +5,13 @@ module Mintsoft
     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)
+        if response.status == 404
+          [] # Return empty array for not found orders
         else
-          case response.status
-          when 404
-            [] # Return empty array for not found
-          else
-            handle_error(response)
-          end
+          response_data = handle_response(response)
+          parse_orders(response_data)
         end
       end
 
@@ -33,4 +28,4 @@ module Mintsoft
       end
     end
   end
-end
+end

data/lib/mintsoft/resources/returns.rb

@@ -7,28 +7,18 @@ module Mintsoft
     class Returns < BaseResource
       def reasons
         response = get_request("/api/Return/Reasons")
-
-        if response.success?
-          parse_reasons(response.body)
-        else
-          handle_error(response)
-        end
+        response_data = handle_response(response)
+        parse_reasons(response_data)
       end
 
       def create(order_id)
         validate_order_id!(order_id)
 
         response = post_request("/api/Return/CreateReturn/#{order_id}")
+        response_data = handle_response(response)
+        response_data["order_id"] = order_id
 
-        if response.success?
-          # Pass entire response to Return object, let Base class handle transformation
-          enhanced_response = response.body.merge({
-            "order_id" => order_id
-          })
-          Objects::Return.new(enhanced_response)
-        else
-          handle_error(response)
-        end
+        Objects::Return.new(response_data)
       end
 
       def add_item(return_id, item_attributes)
@@ -37,20 +27,10 @@ module Mintsoft
 
         payload = format_item_payload(item_attributes)
         response = post_request("/api/Return/#{return_id}/AddItem", body: payload)
+        response_data = handle_response(response)
+        response_data["return_id"] = return_id
 
-        if response.success?
-          # Ensure response.body is a Hash, parse if it's a String
-          response_data = response.body.is_a?(Hash) ? response.body : JSON.parse(response.body)
-          
-          # Return the response as a Return object with original response preserved
-          enhanced_response = response_data.merge({
-            "return_id" => return_id,
-            "item_attributes" => item_attributes
-          })
-          Objects::Return.new(enhanced_response)
-        else
-          handle_error(response)
-        end
+        Objects::Return.new(response_data)
       end
 
       private
@@ -80,8 +60,8 @@ module Mintsoft
       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"]
+          toolkit_result.dig("data", "id") ||
+          toolkit_result["id"]
       end
 
       def format_item_payload(attrs)
@@ -95,4 +75,4 @@ module Mintsoft
       end
     end
   end
-end
+end

data/lib/mintsoft/version.rb

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