mintsoft 0.1.10 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ccd627b64addcd5ce4600e1df832ee931f1e98ff686ab706760cfdbc02f654f
-  data.tar.gz: 130cc96ccd064f08341c96b6ede9f06b5f86278d6dd0f3d2cccb8cbc36fb4a57
+  metadata.gz: f04dc7cd3bc75a9c2b2bc1d7cc36c247003fd0428e9c9a7d03ffc54831640429
+  data.tar.gz: cb488c9c266ddb1b346b5e055872918e59cdee4b6661daf055b95bc463dfca09
 SHA512:
-  metadata.gz: 3597d97e005cf9ff18df541a96d8a3dd3348847f54fbf111b3999cebd1c7d77aea4df83d7ccfd9f5942278c0960a7267eeb79dd26f9d3e4dbad6414b4fb42360
-  data.tar.gz: bb3384d9dc29b08531761d88107695d3b8a79591e23a2d00ef5fa8d06f58597559344cf1689a4b6c4561a647c40d15e3c86524adb7bc0b0ab5beecd970b46d83
+  metadata.gz: a329bf4a4a08129b09d3cf15f22e8e199b56218a747b0ef2007c8fa601913189df67a9b58fbb51d7d93ccad62609aa3cdf30ac043223b648d45983313e275060
+  data.tar.gz: ddd83252d8a4a3140cfce31220c687413b197100fcad8b864bf90dcd20b6e801780000a0f2b24246ed2f64183ef38ad5facd11d3dff330cd8afbdb563e79f2bf

data/README.md

@@ -33,32 +33,46 @@ Or install it yourself as:
 ```ruby
 require 'mintsoft'
 
-# Step 1: Get authentication token
-auth_client = Mintsoft::AuthClient.new
-token = auth_client.auth.authenticate("username", "password")
-
-# Step 2: Initialize client with token
-client = Mintsoft::Client.new(token: token)
-
-# Step 3: Search for orders
-orders = client.orders.search("ORD-2024-001")
-order = orders.first
-
-# Step 4: Get return reasons
-reasons = client.returns.reasons
-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
-result = client.returns.add_item(return_obj.id, {
-  product_id: 123,
-  quantity: 2,
-  reason_id: damage_reason.id,
-  unit_value: 25.00,
-  notes: "Damaged in shipping"
-})
+begin
+  # Step 1: Get authentication token
+  auth_client = Mintsoft::AuthClient.new
+  token = auth_client.auth.authenticate("username", "password")
+
+  # Step 2: Initialize client with token
+  client = Mintsoft::Client.new(token: token)
+
+  # Step 3: Search for orders
+  orders = client.orders.search("ORD-2024-001")
+  if orders.empty?
+    puts "No orders found"
+    return
+  end
+  order = orders.first
+
+  # Step 4: Get return reasons
+  reasons = client.returns.reasons
+  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
+  result = client.returns.add_item(return_obj.id, {
+    product_id: 123,
+    quantity: 2,
+    reason_id: damage_reason.id,
+    unit_value: 25.00,
+    notes: "Damaged in shipping"
+  })
+rescue Mintsoft::AuthClient::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+rescue Mintsoft::AuthenticationError => e
+  puts "Token expired: #{e.message}"
+rescue Mintsoft::ForbiddenError => e
+  puts "Insufficient permissions: #{e.message}"
+rescue Mintsoft::ValidationError => e
+  puts "Validation error: #{e.message}"
+end
 ```
 
 ### API Reference
@@ -70,8 +84,16 @@ result = client.returns.add_item(return_obj.id, {
 auth_client = Mintsoft::AuthClient.new
 
 # Authenticate and get token
-token = auth_client.auth.authenticate("username", "password")
-puts token  # Direct token string
+begin
+  token = auth_client.auth.authenticate("username", "password")
+  puts token  # Direct token string
+rescue Mintsoft::AuthClient::AuthenticationError => e
+  # Invalid credentials when getting auth token
+  puts "Auth failed: #{e.message}"
+rescue Mintsoft::ValidationError => e
+  # Missing username or password
+  puts "Validation error: #{e.message}"
+end
 ```
 
 #### Client
@@ -93,6 +115,9 @@ client = Mintsoft::Client.new(
 # Search for orders by order number
 orders = client.orders.search("ORD-123")
 
+# Retrieve specific order by ID
+order = client.orders.retrieve(order_id)
+
 # Access order properties
 order = orders.first
 puts order.id              # Direct access to order ID
@@ -112,13 +137,18 @@ active_reasons = reasons.select(&:active?)
 return_obj = client.returns.create(order_id)
 
 # Add item to return
-result = client.returns.add_item(return_obj.id, {
-  product_id: 123,
-  quantity: 2,
-  reason_id: reason_id,
-  unit_value: 25.00,
-  notes: "Optional notes"
-})
+begin
+  result = client.returns.add_item(return_obj.id, {
+    product_id: 123,
+    quantity: 2,
+    reason_id: reason_id,
+    unit_value: 25.00,
+    notes: "Optional notes"
+  })
+rescue Mintsoft::ForbiddenError => e
+  # This typically occurs when credentials don't have permission to add items to returns
+  puts "Permission denied: #{e.message}"
+end
 
 # Retrieve a specific return by ID
 return_obj = client.returns.retrieve(return_id)
@@ -140,16 +170,21 @@ All error classes now include response context and status codes for better debug
 begin
   orders = client.orders.search("ORD-123")
 rescue Mintsoft::AuthenticationError => e
-  # Token expired or invalid (401)
+  # Token expired or invalid (401) - for API resource calls
   puts "Authentication failed: #{e.message}"
   puts "Status: #{e.status_code}"
+rescue Mintsoft::AuthClient::AuthenticationError => e
+  # Invalid credentials when getting auth token
+  puts "Auth client authentication failed: #{e.message}"
+  puts "Status: #{e.status_code}"
+rescue Mintsoft::ForbiddenError => e
+  # Insufficient permissions (403) - typically when adding items to returns
+  puts "Insufficient permissions: #{e.message}"
+  puts "Status: #{e.status_code}"
 rescue Mintsoft::ValidationError => e
   # Invalid request data (400)
   puts "Validation error: #{e.message}"
   puts "Response: #{e.response.body if e.response}"
-rescue Mintsoft::NotFoundError => e
-  # Resource not found (404)
-  puts "Not found: #{e.message}"
 rescue Mintsoft::APIError => e
   # General API error
   puts "API error: #{e.message}"
@@ -157,6 +192,24 @@ rescue Mintsoft::APIError => e
 end
 ```
 
+### Not Found Behavior
+
+When resources cannot be found, the gem returns `nil` instead of raising exceptions:
+
+```ruby
+# Search for orders - returns empty array if no orders found
+orders = client.orders.search("NONEXISTENT-ORDER")
+puts orders.empty? # true
+
+# Retrieve specific order - returns nil if not found
+order = client.orders.retrieve(99999)
+puts order.nil? # true
+
+# Retrieve specific return - returns nil if not found
+return_obj = client.returns.retrieve(99999)
+puts return_obj.nil? # true
+```
+
 ### Object Methods
 
 #### Order Objects

data/lib/mintsoft/errors.rb

@@ -18,6 +18,8 @@ module Mintsoft
   # Authentication and authorization errors
   class AuthenticationError < APIError; end
 
+  class ForbiddenError < APIError; end
+
   # Request validation errors
   class ValidationError < APIError; end
 end

data/lib/mintsoft/resources/base_resource.rb

@@ -36,6 +36,7 @@ module Mintsoft
         error_class = case response.status
         when 400 then ValidationError
         when 401 then AuthenticationError
+        when 403 then ForbiddenError
         else APIError
         end
 
@@ -45,10 +46,12 @@ module Mintsoft
 
       def build_error_message(status, error_message)
         case status
-        when 401
-          "Invalid or expired token"
         when 400
           "Invalid request data: #{error_message}"
+        when 401
+          "Invalid or expired token"
+        when 403
+          "Insufficient permissions"
         else
           "API error: #{status} - #{error_message}"
         end

data/lib/mintsoft/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mintsoft
 version: !ruby/object:Gem::Version
-  version: 0.1.10
+  version: 0.1.12
 platform: ruby
 authors:
 - Andy Chong