mintsoft 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 489ff03aa24f063091490ef90057d880e2ae2f181627e9a6bea31ceefdb30149
-  data.tar.gz: '0291ff21beb0f80946eeb3795ee7c98e8e1e45cf7a504fb6995229d72eca6f81'
+  metadata.gz: eb91c29f5e8b482a6b75a67b7d76ab3005ceffb8e448dd6c147822fd9dd5649f
+  data.tar.gz: e00bff92fa1c7d8fb78e725628528e56a9ff46521bd2edcede1c206ee8aa4d6c
 SHA512:
-  metadata.gz: 2c6a650aa2ad9a7c3fc2269763fc8cdcf7bc62f19b24af653500c4c27d56e2cb52e6147b8662a7b8705580976aef6b4a70f1d6063069debbcf6cd49865a4c36a
-  data.tar.gz: 7b8722786821c4d3adabfb7b7fdb7495af8cb0a08c0bdc8272a0667fe2f39e227e846885cfdbae7720568943ebf203fd5279aca49c05517b90851fd910ef2e08
+  metadata.gz: 38e7aea2dbb674599085f32697c34ddf0c91739049dbba85d339aad060409c8e8d4b36ad509133aaf0321c58e36fb5171bc61069210476342214b794b9b2e2cc
+  data.tar.gz: '0837bb4b72c7f50323e62ee569757f793d2fd5a3c895f8aaedcaed1bc3e7cdff98d080436ab9e9e0e780c92e267d30fd62d1823764e3504f3ac3085f696bc519'

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,7 @@ module Mintsoft
         end
 
         if response.success?
-          handle_success_response(response.body)
+          response.body
         else
           handle_error_response(response)
         end
@@ -59,13 +59,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 +77,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

@@ -6,8 +6,11 @@ require "ostruct"
 
 module Mintsoft
   class Base < OpenStruct
+    attr_reader :original_response
+
     def initialize(attributes)
-      super to_ostruct(attributes)
+      @original_response = deep_freeze_object(attributes)
+      super(to_ostruct(attributes))
     end
 
     def to_ostruct(obj)
@@ -20,17 +23,33 @@ 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)
+      case obj
+      when Hash
+        obj.transform_values { |value| deep_freeze_object(value) }.freeze
+      when Array
+        obj.map { |item| deep_freeze_object(item) }.freeze
+      else
+        obj.respond_to?(:freeze) ? obj.freeze : obj
+      end
+    end
+
     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) }
@@ -41,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

@@ -1,34 +1,24 @@
 # frozen_string_literal: true
 
+require "json"
+
 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
+        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?
-          # 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
+        Objects::Return.new(response_data)
       end
 
       def add_item(return_id, item_attributes)
@@ -37,12 +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?
-          true # Simple success indicator
-        else
-          handle_error(response)
-        end
+        Objects::Return.new(response_data)
       end
 
       private
@@ -72,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)
@@ -87,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.0"
+  VERSION = "0.1.2"
 end