petstore_api_client 0.1.0

data/lib/petstore_api_client/models/base.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module PetstoreApiClient
+  module Models
+    # Base class for all API models
+    # Provides common ActiveModel functionality and shared behavior
+    #
+    # This follows the DRY principle by centralizing all the common
+    # ActiveModel includes that every model needs.
+    #
+    # Benefits:
+    # - Single place to add model-wide functionality
+    # - Consistent behavior across all models
+    # - Reduces boilerplate in model classes
+    class Base
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+      include ActiveModel::Validations
+      include ActiveModel::Serialization
+
+      # Convert model to hash for API requests
+      # Subclasses can override this for custom serialization
+      # Default implementation uses compact to remove nil values
+      def to_h
+        attributes.compact
+      end
+
+      # Create model instance from API response data
+      # This is a template method - subclasses must implement their own
+      # field mapping logic since each model has different fields
+      #
+      # @param data [Hash] Response data from API
+      # @return [Base, nil] Model instance or nil if data is nil
+      def self.from_response(data)
+        raise NotImplementedError, "#{name} must implement .from_response"
+      end
+
+      class << self
+        protected
+
+        # Helper method to extract value from response data
+        # Tries multiple key formats: camelCase, snake_case, symbol
+        #
+        # @param data [Hash] Response data
+        # @param field [Symbol] Field name in snake_case
+        # @param api_key [String, nil] Optional camelCase API key (if different from field)
+        # @return [Object, nil] Field value or nil
+        def extract_field(data, field, api_key = nil)
+          return nil if data.nil?
+
+          # Try API key (camelCase) first if provided
+          value = data[api_key] if api_key
+          # Then try snake_case string and symbol
+          value ||= data[field.to_s] || data[field]
+          value
+        end
+      end
+    end
+  end
+end

data/lib/petstore_api_client/models/category.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "named_entity"
+
+module PetstoreApiClient
+  module Models
+    # Category model - represents a pet category
+    # Inherits all behavior from NamedEntity (id + name)
+    #
+    # Refactored to eliminate 100% duplication with Tag model
+    # by inheriting from shared NamedEntity base class
+    class Category < NamedEntity
+      # Category-specific logic can be added here if needed
+      # For now, it just uses the base NamedEntity behavior
+    end
+  end
+end

data/lib/petstore_api_client/models/named_entity.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PetstoreApiClient
+  module Models
+    # Base class for simple entities with just ID and name
+    # Used by Category and Tag models to eliminate duplication
+    #
+    # This is an example of the DRY principle - both Category and Tag
+    # were 100% identical, so we extracted their common behavior here.
+    class NamedEntity < Base
+      attribute :id, :integer
+      attribute :name, :string
+
+      # Override to_h to use symbol keys (API expects this format)
+      def to_h
+        {
+          id: id,
+          name: name
+        }.compact
+      end
+
+      # Create from API response data
+      # Handles both string and symbol keys
+      def self.from_response(data)
+        return nil if data.nil?
+
+        new(
+          id: extract_field(data, :id),
+          name: extract_field(data, :name)
+        )
+      end
+    end
+  end
+end

data/lib/petstore_api_client/models/order.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module PetstoreApiClient
+  module Models
+    # Order model representing a store order
+    # TODO: Should validate quantity > 0 and pet_id presence, but assignment doc didn't specify
+    class Order < Base
+      VALID_STATUSES = %w[placed approved delivered].freeze
+
+      attribute :id, :integer
+      attribute :pet_id, :integer
+      attribute :quantity, :integer
+      attribute :ship_date, :datetime
+      attribute :status, :string
+      attribute :complete, :boolean, default: false
+
+      validates :status, enum: { in: VALID_STATUSES, allow_nil: true }, if: -> { status.present? }
+
+      # Note: API expects snake_case to be converted to camelCase
+      def to_h
+        {
+          id: id,
+          petId: pet_id,
+          quantity: quantity,
+          shipDate: ship_date&.iso8601,
+          status: status,
+          complete: complete
+        }.compact
+      end
+
+      def self.from_response(data)
+        return nil if data.nil?
+
+        # Parse ship_date if it's a string
+        ship_date = data["shipDate"] || data[:shipDate] || data[:ship_date]
+        ship_date = parse_datetime(ship_date) if ship_date.is_a?(String)
+
+        new(
+          id: data["id"] || data[:id],
+          pet_id: data["petId"] || data[:petId] || data[:pet_id],
+          quantity: data["quantity"] || data[:quantity],
+          ship_date: ship_date,
+          status: data["status"] || data[:status],
+          complete: data["complete"] || data[:complete] || false
+        )
+      end
+
+      def self.parse_datetime(datetime_string)
+        DateTime.parse(datetime_string)
+      rescue ArgumentError
+        nil # Silently fail - API shouldn't send invalid dates anyway
+      end
+    end
+  end
+end

data/lib/petstore_api_client/models/pet.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module PetstoreApiClient
+  module Models
+    # Pet resource model
+    #
+    # Represents a pet in the Petstore API with comprehensive validations
+    # following the API specification. Uses ActiveModel for validation,
+    # attribute management, and serialization.
+    #
+    # The Pet model supports:
+    # - Required and optional attributes with type casting
+    # - Nested objects (Category, Tags)
+    # - Status enum validation
+    # - Bi-directional conversion (to API format and from API responses)
+    # - ActiveModel validations
+    #
+    # @example Creating a new pet
+    #   pet = Pet.new(
+    #     name: "Fluffy",
+    #     status: "available",
+    #     photo_urls: ["https://example.com/photo1.jpg"]
+    #   )
+    #
+    # @example Creating a pet with nested category
+    #   pet = Pet.new(
+    #     name: "Fluffy",
+    #     status: "available",
+    #     category: { id: 1, name: "Dogs" },
+    #     tags: [{ id: 1, name: "friendly" }],
+    #     photo_urls: ["https://example.com/photo1.jpg"]
+    #   )
+    #
+    # @example Creating from API response
+    #   data = { "id" => 123, "name" => "Fluffy", "status" => "available" }
+    #   pet = Pet.from_response(data)
+    #
+    # @example Converting to API format
+    #   pet_hash = pet.to_h
+    #   # Returns: { id: 123, name: "Fluffy", photoUrls: [...], status: "available" }
+    #
+    # @see Category
+    # @see Tag
+    # @since 0.1.0
+    class Pet < Base
+      # Valid pet status values per API specification
+      VALID_STATUSES = %w[available pending sold].freeze
+
+      # @!attribute [rw] id
+      #   @return [Integer, nil] Pet ID (assigned by server)
+      attribute :id, :integer
+
+      # @!attribute [rw] name
+      #   @return [String] Pet name (required)
+      attribute :name, :string
+
+      # @!attribute [rw] photo_urls
+      #   @return [Array<String>] URLs of pet photos (required, minimum 1)
+      attribute :photo_urls, default: -> { [] }
+
+      # @!attribute [rw] status
+      #   @return [String, nil] Pet status (available, pending, or sold)
+      attribute :status, :string
+
+      # @!attribute [rw] category
+      #   @return [Category, nil] Pet category (optional nested object)
+      # @!attribute [rw] tags
+      #   @return [Array<Tag>] Pet tags (optional nested objects)
+      attr_accessor :category, :tags
+
+      # Validations per API specification
+      validates :name, presence: true, length: { minimum: 1 }
+      validates :photo_urls, array_presence: true
+      validates :status, enum: { in: VALID_STATUSES, allow_nil: true }, if: -> { status.present? }
+
+      # Validate nested category if present
+      validate :category_valid, if: -> { category.present? }
+
+      # Validate nested tags if present
+      validate :tags_valid, if: -> { tags.present? && tags.any? }
+
+      # Initialize a new Pet model
+      #
+      # Accepts attributes as a hash and builds nested Category and Tag objects
+      # if provided. Handles both symbol and string keys.
+      #
+      # @param attributes [Hash] Pet attributes
+      # @option attributes [Integer] :id Pet ID (optional, assigned by server)
+      # @option attributes [String] :name Pet name (required)
+      # @option attributes [Array<String>] :photo_urls Photo URLs (required)
+      # @option attributes [String] :status Pet status (available, pending, sold)
+      # @option attributes [Hash, Category] :category Category data or object
+      # @option attributes [Array<Hash>, Array<Tag>] :tags Array of tag data or objects
+      #
+      # @example
+      #   pet = Pet.new(name: "Fluffy", photo_urls: ["http://example.com/1.jpg"])
+      #
+      def initialize(attributes = {})
+        # Handle category separately since it's a nested object
+        category_data = attributes.delete(:category) || attributes.delete("category")
+        @category = build_category(category_data) if category_data
+
+        # Handle tags separately since they're nested objects
+        tags_data = attributes.delete(:tags) || attributes.delete("tags")
+        @tags = build_tags(tags_data) if tags_data
+
+        super
+      end
+
+      # Convert pet to hash for API requests
+      #
+      # Converts the pet object to a hash suitable for API requests.
+      # Uses camelCase keys as expected by the Petstore API.
+      # Nested objects (category, tags) are also converted to hashes.
+      # Nil values are removed from the output.
+      #
+      # @return [Hash] Pet data in API format with camelCase keys
+      #
+      # @example
+      #   pet = Pet.new(name: "Fluffy", photo_urls: ["http://example.com/1.jpg"])
+      #   pet.to_h
+      #   # => { name: "Fluffy", photoUrls: ["http://example.com/1.jpg"] }
+      #
+      def to_h
+        # puts "Converting pet to hash: #{name}" if ENV['DEBUG']
+        {
+          id: id,
+          category: category&.to_h,
+          name: name,
+          photoUrls: photo_urls, # camelCase for API
+          tags: tags&.map(&:to_h),
+          status: status
+        }.compact # Remove nil values
+      end
+
+      # Create Pet instance from API response data
+      #
+      # Factory method that creates a Pet object from API response data.
+      # Handles both string and symbol keys, and converts camelCase API
+      # keys (photoUrls) to snake_case Ruby convention (photo_urls).
+      #
+      # @param data [Hash, nil] API response data
+      # @return [Pet, nil] New Pet instance, or nil if data is nil
+      #
+      # @example
+      #   response_data = {
+      #     "id" => 123,
+      #     "name" => "Fluffy",
+      #     "photoUrls" => ["http://example.com/1.jpg"],
+      #     "status" => "available"
+      #   }
+      #   pet = Pet.from_response(response_data)
+      #
+      def self.from_response(data)
+        return nil if data.nil?
+
+        new(
+          id: data["id"] || data[:id],
+          name: data["name"] || data[:name],
+          photo_urls: data["photoUrls"] || data[:photoUrls] || data[:photo_urls],
+          category: data["category"] || data[:category],
+          tags: data["tags"] || data[:tags],
+          status: data["status"] || data[:status]
+        )
+      end
+
+      private
+
+      # Build Category object from data
+      #
+      # @param category_data [Hash, Category, nil] Category data or object
+      # @return [Category, nil] Category instance or nil
+      # @api private
+      def build_category(category_data)
+        return nil if category_data.nil?
+        return category_data if category_data.is_a?(Category)
+
+        Category.new(category_data)
+      end
+
+      # Build array of Tag objects from data
+      #
+      # @param tags_data [Array<Hash>, Array<Tag>, nil] Array of tag data or objects
+      # @return [Array<Tag>] Array of Tag instances
+      # @api private
+      def build_tags(tags_data)
+        return [] if tags_data.nil? || !tags_data.is_a?(Array)
+
+        tags_data.map do |tag_data|
+          tag_data.is_a?(Tag) ? tag_data : Tag.new(tag_data)
+        end
+      end
+
+      # Validate nested category object
+      #
+      # Custom validator that checks if the nested category is valid.
+      # Adds error messages from category to this pet's errors.
+      #
+      # @return [void]
+      # @api private
+      def category_valid
+        return unless category.present?
+        return if category.valid?
+
+        errors.add(:category, "is invalid: #{category.errors.full_messages.join(", ")}")
+      end
+
+      # Validate nested tag objects
+      #
+      # Custom validator that checks if all tags are valid.
+      # Adds error if any tags are invalid.
+      #
+      # @return [void]
+      # @api private
+      def tags_valid
+        return unless tags.is_a?(Array)
+
+        invalid_tags = tags.reject(&:valid?)
+        return if invalid_tags.empty?
+
+        errors.add(:tags, "contain invalid entries")
+      end
+    end
+  end
+end

data/lib/petstore_api_client/models/tag.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "named_entity"
+
+module PetstoreApiClient
+  module Models
+    # Tag model - represents a pet tag
+    # Inherits all behavior from NamedEntity (id + name)
+    #
+    # Refactored to eliminate 100% duplication with Category model
+    # by inheriting from shared NamedEntity base class
+    #
+    # Keeping this as a separate class (rather than aliasing to Category)
+    # in case we need to add tag-specific logic later
+    class Tag < NamedEntity
+      # Tag-specific logic can be added here if needed
+      # For now, it just uses the base NamedEntity behavior
+    end
+  end
+end

data/lib/petstore_api_client/paginated_collection.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module PetstoreApiClient
+  # Wrapper for paginated API responses
+  # Provides metadata about pagination along with the data
+  #
+  # This follows the Decorator pattern - it wraps an array
+  # with additional pagination information
+  class PaginatedCollection
+    include Enumerable
+
+    attr_reader :data, :page, :per_page, :total_count
+
+    # Initialize a paginated collection
+    #
+    # @param data [Array] The array of items for this page
+    # @param page [Integer] Current page number (1-indexed)
+    # @param per_page [Integer] Number of items per page
+    # @param total_count [Integer, nil] Total number of items across all pages (if known)
+    def initialize(data:, page: 1, per_page: 25, total_count: nil)
+      @data = Array(data)
+      @page = page.to_i
+      @per_page = per_page.to_i
+      @total_count = total_count&.to_i
+    end
+
+    # Delegate enumerable methods to data array
+    def each(&)
+      data.each(&)
+    end
+
+    # Number of items in current page
+    def count
+      data.count
+    end
+    alias size count
+    alias length count
+
+    # Check if there are more pages available
+    # Returns true if we have total_count and current page isn't the last
+    # Returns nil if total_count is unknown (can't determine)
+    # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
+    def next_page?
+      return nil if total_count.nil?
+
+      page < total_pages
+    end
+    # rubocop:enable Style/ReturnNilInPredicateMethodDefinition
+
+    # Check if there's a previous page
+    def prev_page?
+      page > 1
+    end
+    alias previous_page? prev_page?
+
+    # Get next page number (nil if on last page or unknown)
+    def next_page
+      next_page? ? page + 1 : nil
+    end
+
+    # Get previous page number (nil if on first page)
+    def prev_page
+      prev_page? ? page - 1 : nil
+    end
+    alias previous_page prev_page
+
+    # Calculate total number of pages
+    # Returns nil if total_count is unknown
+    def total_pages
+      return nil if total_count.nil?
+      return 1 if total_count.zero?
+
+      (total_count.to_f / per_page).ceil
+    end
+
+    # Check if this is the first page
+    def first_page?
+      page == 1
+    end
+
+    # Check if this is the last page
+    # Returns nil if total_count is unknown
+    # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
+    def last_page?
+      return nil if total_count.nil?
+
+      page >= total_pages
+    end
+    # rubocop:enable Style/ReturnNilInPredicateMethodDefinition
+
+    # Get offset for current page (0-indexed)
+    def offset
+      (page - 1) * per_page
+    end
+
+    # Check if collection is empty
+    def empty?
+      data.empty?
+    end
+
+    # Check if collection has any items
+    def any?
+      !empty?
+    end
+
+    # Convert to array (returns the data)
+    def to_a
+      data
+    end
+    alias to_ary to_a
+
+    # Summary information about pagination
+    def pagination_info
+      {
+        page: page,
+        per_page: per_page,
+        count: count,
+        total_count: total_count,
+        total_pages: total_pages,
+        next_page: next_page,
+        prev_page: prev_page,
+        first_page: first_page?,
+        last_page: last_page?
+      }
+    end
+
+    # Inspect override for better debugging
+    def inspect
+      "#<PaginatedCollection page=#{page}/#{total_pages || "?"} " \
+        "per_page=#{per_page} count=#{count} total=#{total_count || "?"}>"
+    end
+  end
+end