mintsoft 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f77c74116b807d8a07ce73ccf258237db3665585ede056cc00d08044fe811497
-  data.tar.gz: 06e3a80cc0b9e2f38424116875c5e96fd0a78d78dfb7fb8c3330824e3fdf2600
+  metadata.gz: f317c96d49df00a91bb679b079da14192f53ee373bedd233b68a373694f82528
+  data.tar.gz: 181fbdf0b85db468c9537dc1fb2c4d8cb41c8651487056cc9e71a8b3007f41ac
 SHA512:
-  metadata.gz: 4a443a1a412560f0dd8f97fd00a2aacbc2dc1ce3186bf5e59cf67e4dfb968661db32dda6fa2dc0591e8032fb696da461348b68c7c474471c53c5a1e2c90d8cab
-  data.tar.gz: 01a64e1ec0b9415434f6dcc3ba9f36f98d0e97121e1ef9b2cf301862053f5e2a086ba8b4d3d2c9ba75c855c78d2400435a57b8342070a26810461d3353b894e0
+  metadata.gz: 122feb85df1c698d875f4494f5b3a31a9401378ff0629bcf5328ccaa26d06057bc0f7f0b6b5213762c663a2220d48569c3b9fd5f226f0969fd72c44fec0b37e5
+  data.tar.gz: 4e5db4e19ff76da89ae50dd1d05d3303d1e4dc34a0c32896875fad648795acf1f86a0760914faf5f244012308451294d083a5a9aec35f82ddd4456baf8d260b1

data/CLAUDE.md

@@ -0,0 +1,92 @@
+# Mintsoft Ruby Gem - Claude Instructions
+
+## Project Overview
+
+This is a Ruby gem that provides a wrapper for the Mintsoft API with token-based authentication and access to warehouse management functions.
+
+## Core Principles
+
+### API Response Handling - CRITICAL RULE
+**DO NOT ENHANCE OR INJECT DATA TO THE RESPONSE WHEN WRAPPING THE API RESPONSE IN OBJECT**
+
+- The `Base` class (lib/mintsoft/base.rb) wraps API responses in OpenStruct objects
+- Objects should only contain data that comes directly from the API response
+- DO NOT add computed properties, injected fields, or derived data
+- Preserve the original response structure exactly as returned by the API
+- Use `@original_response` to store the frozen, unmodified API response
+
+### Object Design
+- All API objects inherit from `Mintsoft::Objects::Base`
+- Base class provides OpenStruct functionality with underscore key transformation
+- Objects provide `.raw` method to access original API response
+- Objects provide `.to_hash` method to convert back to hash representation
+- Keep object classes simple - they are data containers, not business logic
+
+## Project Structure
+
+```
+lib/
+├── mintsoft/
+│   ├── base.rb                 # Base class for all API objects
+│   ├── client.rb              # Main API client
+│   ├── auth_client.rb         # Authentication client
+│   ├── resources/             # API resource handlers
+│   └── objects/               # API response objects
+│       ├── order.rb           # Order object (inherits from Base)
+│       └── return.rb          # Return object (inherits from Base)
+```
+
+## Development Guidelines
+
+### When Adding New Object Classes
+1. Inherit from `Mintsoft::Objects::Base`
+2. Keep the class minimal - let Base handle the data transformation
+3. DO NOT add computed properties or inject additional data
+4. Test with actual API responses to ensure correct transformation
+
+### When Modifying Base Class
+1. Maintain backward compatibility
+2. Preserve original response data integrity
+3. Ensure `to_hash` and `raw` methods continue to work
+4. Test key transformation (camelCase to underscore)
+
+### Error Handling
+- All error classes should include response context and status codes
+- Provide clear error messages for common scenarios
+- Use appropriate HTTP status-based error classes
+
+### Authentication
+- Token management is manual - no automatic refresh
+- Auth client returns token directly as string
+- Client initialization requires explicit token parameter
+
+## Testing
+
+- Run tests with `rake spec`
+- Test with real API responses when possible
+- Ensure object transformation preserves data integrity
+- Test error scenarios with appropriate status codes
+
+## Key Files to Understand
+
+1. `lib/mintsoft/base.rb` - Core object transformation logic
+2. `lib/mintsoft/client.rb` - Main API client interface
+3. `lib/mintsoft/auth_client.rb` - Authentication handling
+4. `spec/` - Test files showing expected behavior
+
+## When Making Changes
+
+1. Read the existing code patterns first
+2. Follow Ruby conventions and the existing style
+3. **NEVER inject or enhance API response data**
+4. Keep object classes simple and focused on data representation
+5. Maintain the original response preservation pattern
+6. Test thoroughly with real API responses
+
+## Common Pitfalls to Avoid
+
+- Adding computed properties to object classes
+- Modifying API response data during object creation
+- Breaking the `@original_response` storage pattern
+- Adding business logic to data objects
+- Changing key transformation behavior without testing

data/README.md

@@ -122,7 +122,6 @@ result = client.returns.add_item(return_obj.id, {
 
 # 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
 ```
 
@@ -173,7 +172,6 @@ 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
 ```
 
@@ -189,7 +187,7 @@ puts token  # Direct token string
 client = Mintsoft::Client.new(token: token)
 
 # For re-authentication when token expires:
-token = auth_client.auth.authenticate("username", "password") 
+token = auth_client.auth.authenticate("username", "password")
 client = Mintsoft::Client.new(token: token)
 ```
 

data/lib/mintsoft/auth_client.rb

@@ -5,6 +5,9 @@ require "faraday/net_http"
 
 module Mintsoft
   class AuthClient
+    # Authentication errors specific to auth client
+    class AuthenticationError < APIError; end
+
     BASE_URL = "https://api.mintsoft.co.uk"
 
     attr_reader :base_url, :conn_opts
@@ -67,7 +70,7 @@ module Mintsoft
       def handle_error_response(response)
         case response.status
         when 401
-          raise AuthenticationError, "Invalid credentials"
+          raise AuthClient::AuthenticationError, "Invalid credentials"
         when 400
           raise ValidationError, "Invalid request: #{extract_error_message(response.body)}"
         else

data/lib/mintsoft/errors.rb

@@ -15,6 +15,7 @@ module Mintsoft
   # General API-related errors
   class APIError < Error; end
 
+
   # Authentication and authorization errors
   class AuthenticationError < APIError; end
 

data/lib/mintsoft/resources/returns.rb

@@ -16,7 +16,6 @@ module Mintsoft
 
         response = post_request("/api/Return/CreateReturn/#{order_id}")
         response_data = handle_response(response)
-        response_data["order_id"] = order_id
 
         Objects::Return.new(response_data)
       end
@@ -28,7 +27,6 @@ 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
 
         Objects::Return.new(response_data)
       end

data/lib/mintsoft/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mintsoft
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Andy Chong
@@ -111,11 +111,11 @@ files:
 - ".serena/project.yml"
 - ".standard.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
-- examples/complete_workflow.rb
 - lib/mintsoft.rb
 - lib/mintsoft/auth_client.rb
 - lib/mintsoft/base.rb

data/examples/complete_workflow.rb

@@ -1,140 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Complete workflow example for the Mintsoft gem
-# This demonstrates all 5 endpoints working together
-
-require "mintsoft"
-
-# Step 1: Authentication using AuthClient
-puts "=== Step 1: Authentication ==="
-auth_client = Mintsoft::AuthClient.new
-begin
-  token = auth_client.auth.authenticate(
-    ENV.fetch("MINTSOFT_USERNAME"),
-    ENV.fetch("MINTSOFT_PASSWORD")
-  )
-
-  puts "✅ Authentication successful!"
-  puts "Token: #{token[0...10]}..."
-rescue Mintsoft::AuthenticationError => e
-  puts "❌ Authentication failed: #{e.message}"
-  exit 1
-rescue KeyError => e
-  puts "❌ Environment variable not set: #{e.message}"
-  puts "Please set MINTSOFT_USERNAME and MINTSOFT_PASSWORD environment variables"
-  exit 1
-end
-
-# Step 2: Initialize client with token
-puts "\n=== Step 2: Initialize Client ==="
-client = Mintsoft::Client.new(token: token)
-puts "✅ Client initialized with token"
-
-# Step 3: Search for orders
-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
-rescue Mintsoft::AuthenticationError => e
-  puts "❌ Authentication error: #{e.message}"
-  puts "Token may have expired. Please re-authenticate."
-  exit 1
-rescue Mintsoft::APIError => e
-  puts "❌ API error: #{e.message}"
-  exit 1
-end
-
-# Step 4: Get return reasons
-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
-end
-
-# Step 5: Create return
-puts "\n=== Step 5: Create Return ==="
-begin
-  return_obj = client.returns.create(order.id)
-  puts "✅ Return created successfully!"
-  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
-rescue Mintsoft::APIError => e
-  puts "❌ API error: #{e.message}"
-  exit 1
-end
-
-# Step 6: Add item to return
-puts "\n=== Step 6: Add Item to Return ==="
-item_attributes = {
-  product_id: 123,                    # Replace with actual product ID
-  quantity: 2,                        # Quantity to return
-  reason_id: selected_reason.id,      # Selected return reason
-  unit_value: 25.00,                  # Unit value
-  notes: "Damaged during shipping"    # Optional notes
-}
-
-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]}"
-    puts "Quantity: #{item_attributes[:quantity]}"
-    puts "Reason: #{selected_reason.name}"
-    puts "Unit Value: $#{item_attributes[:unit_value]}"
-    puts "Notes: #{item_attributes[:notes]}"
-  else
-    puts "❌ Failed to add item to return"
-  end
-rescue Mintsoft::ValidationError => e
-  puts "❌ Validation error: #{e.message}"
-rescue Mintsoft::APIError => e
-  puts "❌ API error: #{e.message}"
-end
-
-puts "\n=== Workflow Complete ==="
-puts "🎉 Successfully completed the full Mintsoft API workflow!"
-puts "   1. ✅ Authenticated and got token"
-puts "   2. ✅ Initialized client"
-puts "   3. ✅ Searched for orders"
-puts "   4. ✅ Retrieved return reasons"
-puts "   5. ✅ Created return"
-puts "   6. ✅ Added item to return"