packwizard-parser 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1698bc9057932aac887cd13f6915783b0e6145889a88a7aff87edcf063f26ca1
+  data.tar.gz: ca8d40daa24f1cfff4d53d344b5297612697613e021df223f27147c56d4893e7
+SHA512:
+  metadata.gz: '028bcb01a18923c2f3f1a2203ed5c534c7c9cbeb742c6b61b1b8decefd1d7261689bbfff75f1de2401c31535376ba812c61fc0ecd4db98e0505cb25f0690972a'
+  data.tar.gz: ec0976146390b00f5d8c9c99be876c4720fd0373e84947d38c452d579f80ce03cd4d7f572fe319852941dd4373dcbd8033e4db96b433589dbcf4c83c6461a198

data/README.md

@@ -0,0 +1,144 @@
+# PackWizard Parser
+
+A Ruby gem for parsing PackWizard lists from URLs.
+
+Used by [Goulight](https://goulight.com). Source: [github.com/goulight/packwizard-parser](https://github.com/goulight/packwizard-parser).
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'packwizard-parser', git: 'https://github.com/goulight/packwizard-parser.git'
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install packwizard-parser
+```
+
+## Usage
+
+`PackwizardParser::Parser#parse` (and `PackwizardParser.parse_url`) return a **`PackwizardParser::List`** object with readers `name`, `description`, and `categories`. Each category is a **`PackwizardParser::Category`**; each item is a **`PackwizardParser::Item`**.
+
+Call **`#to_h`** on the list (or on categories/items) if you need nested hashes (for example JSON APIs).
+
+### Parse from URL or ID
+
+```ruby
+require 'packwizard_parser'
+
+# With full URL
+list = PackwizardParser::Parser.new(shareable_id: 'https://www.packwizard.com/s/Dv5388R').parse
+
+# With ID
+list = PackwizardParser::Parser.new(shareable_id: 'Dv5388R').parse
+
+# Or using the convenience method
+list = PackwizardParser.parse_url('https://www.packwizard.com/s/Dv5388R')
+list = PackwizardParser.parse_url('Dv5388R')
+
+list.name                    # => "List Name"
+list.description             # => "List description" or nil
+list.categories.first.name   # => "Category Name"
+
+item = list.categories.first.items.first
+item.name                    # => "Item Name"
+item.description             # => "Item description" or nil
+item.weight                  # => 476.0   # grams per unit
+item.total_weight            # => 476.0   # weight * quantity (grams)
+item.quantity                # => 1
+item.image_url               # => "https://..." or nil
+item.consumable              # => false
+item.total_consumable_weight # => nil (or total grams if consumable)
+item.worn                    # => false
+item.worn_quantity           # => 0 (or 1 if worn)
+item.total_worn_weight       # => 0.0 (or grams worn, weight × 1)
+
+# Hash shape (matches nested #to_h):
+list.to_h
+# => {
+#   name: "List Name",
+#   description: nil,
+#   categories: [
+#     {
+#       name: "Category Name",
+#       description: nil,
+#       items: [
+#         {
+#           name: "Item Name",
+#           description: "Item description",
+#           weight: 476.0,
+#           total_weight: 476.0,
+#           quantity: 1,
+#           image_url: "https://...",
+#           consumable: false,
+#           total_consumable_weight: nil,
+#           worn: false,
+#           worn_quantity: 0,
+#           total_worn_weight: 0.0
+#         }
+#       ]
+#     }
+#   ]
+# }
+```
+
+## Running Tests
+
+To run the test suite:
+
+```bash
+rspec
+```
+
+## Test Fixtures
+
+Test fixtures are stored in `spec/fixtures/` and contain JSON from example PackWizard lists:
+
+- `negative.json` - This data with negative / empty values
+- `tUE6BJs.json` - A copy from Ultralight Gear List 2023 (Dv5388R)
+
+To update fixtures, download fresh JSON:
+
+```bash
+curl -s 'https://www.packwizard.com/api/packs/getSharedPackWithId?shareableId=Dv5388R' > spec/fixtures/Dv5388R.json
+```
+
+## Features
+
+- Parses list name and description
+- Extracts categories with descriptions
+- Extracts items with:
+    - Name and description
+    - Weight per unit and total weight (automatically converted to grams)
+    - Quantity
+    - Image URLs
+    - Consumable flag and total consumable weight when applicable
+    - Worn flag, worn quantity, and total worn weight when applicable
+- Supports weight units: oz, lb, g, kg (all converted to grams)
+- Handles URL's
+
+## Weight Conversion
+
+The parser automatically converts all weights to grams:
+
+- `oz` → multiply by 28.3495
+- `lb` → multiply by 453.592
+- `g` → use as-is
+- `kg` → multiply by 1000
+
+## Development
+
+To install dependencies locally:
+
+```bash
+bundle install
+```

data/lib/packwizard_parser/category.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module PackwizardParser
+  # Represents a Category from a PackWizard list
+  #
+  # @attr_reader [String] name The name of the category
+  # @attr_reader [String, nil] description Optional description of the category
+  # @attr_reader [Array<Item>] items Array of items in this category
+  class Category
+    attr_reader :name, :description, :items
+
+    # @param [String] name The name of the category
+    # @param [String, nil] description Optional description of the category
+    # @param [Array<Item>] items Array of items in this category
+    def initialize(name:, description: nil, items: [])
+      @name = name
+      @description = description
+      @items = items
+    end
+
+    # Convert to hash for backward compatibility
+    # @return [Hash] Hash representation of the category
+    def to_h
+      {
+        name: name,
+        description: description,
+        items: items.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/packwizard_parser/category_parser.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module PackwizardParser
+  # Parser for extracting category data from PackWizard JSON
+  class CategoryParser
+    # Parse all categories from a PackWizard JSON
+    #
+    # @param data [Hash] The parsed JSON response
+    # @param item_parser [ItemParser] The parser used for extracting items from each category
+    # @return [Array<Category>] Array of extracted categories
+    def parse_all(data, item_parser:)
+      categories = []
+
+      # tableData contains the arrays of each category
+      data['tableData'].each do |category_data|
+        category = parse(category_data, item_parser: item_parser)
+        categories << category if category
+      end
+      categories
+    end
+
+    private
+
+    # Parse a single category row
+    #
+    # @param category_data [Hash] A single entry from data['tableData']
+    def parse(category_data, item_parser:)
+      name = extract_name(category_data)
+
+      description = extract_description(category_data)
+
+      items = extract_items(category_data, item_parser: item_parser)
+
+      Category.new(name: name, description: description, items: items)
+    end
+
+    def extract_name(category_data)
+      name = category_data['title']
+      return name unless name.nil? || name.empty?
+
+      'Untitled category' # Fallback if name is not set
+    end
+
+    def extract_description(category_data)
+      description = category_data['subtitle']
+      return description unless description.nil? || description.empty?
+
+      nil
+    end
+
+    def extract_items(category_data, item_parser:)
+      rows = category_data['rows']
+      return [] unless rows
+
+      rows.values.map do |row|
+        item_parser.parse(row)
+      end
+    end
+  end
+end

data/lib/packwizard_parser/gram_converter.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module PackwizardParser
+
+  module GramConverter
+    # Conversion factors for each unit to grams
+    FACTORS = {
+      'g' => 1.0,
+      'kg' => 1000.0,
+      'oz' => 28.35,
+      'lb' => 453.59
+    }.freeze
+
+    # Convert the value to grams
+    #
+    # @param value [Float] The value to convert
+    # @param unit [String] The unit extracted from the JSON
+    # @return [Float] The converted value in grams
+    def self.convert(value:, unit:)
+      factor = FACTORS.fetch(unit.to_s.downcase, 1.0)
+      (value * factor)
+    end
+  end
+end

data/lib/packwizard_parser/item.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module PackwizardParser
+  # Represents a single item in a PackWizard list
+  #
+  # @attr_reader [String] name The name of the item
+  # @attr_reader [String, nil] description Optional description of the item
+  # @attr_reader [Float] weight Weight per item in grams
+  # @attr_reader [Float] total_weight Total weight (weight * quantity) in grams
+  # @attr_reader [Integer] quantity Number of items
+  # @attr_reader [String, nil] image_url Optional URL to item image
+  # @attr_reader [Boolean] consumable Whether the item is consumable
+  # @attr_reader [Float, nil] total_consumable_weight Total consumable weight
+  #   (weight * quantity) if consumable, nil otherwise
+  # @attr_reader [Boolean] worn Whether the item is worn
+  # @attr_reader [Integer] worn_quantity Number of worn items (always 1 if worn, 0 otherwise)
+  # @attr_reader [Float] total_worn_weight Total worn weight (weight * 1) if worn, 0.0 otherwise
+  class Item
+    attr_reader :name, :description, :weight, :total_weight, :quantity, :price, :total_price, :image_url,
+                :consumable, :total_consumable_weight, :worn, :worn_quantity, :total_worn_weight
+    # @param name [String] The name of the item
+    # @param description [String, nil] Optional description
+    # @param weight [Float] Weight per item in grams
+    # @param total_weight [Float] Total weight (weight * quantity) in grams
+    # @param quantity [Integer] Number of items
+    # @param image_url [String, nil] Optional URL to item image
+    # @param consumable [Boolean] Whether the item is consumable
+    # @param total_consumable_weight [Float, nil] Total consumable weight if consumable
+    # @param worn [Boolean] Whether the item is worn
+    # @param worn_quantity [Integer] Number of worn items (1 if worn)
+    # @param total_worn_weight [Float] Total worn weight if worn
+    def initialize(name:, weight:, total_weight:, quantity:, description: nil,
+                   image_url: nil, consumable: false, total_consumable_weight: nil,
+                   worn: false, worn_quantity:, total_worn_weight:)
+      @name = name
+      @weight = weight
+      @description = description
+      @total_weight = total_weight
+      @quantity = quantity
+      @image_url = image_url
+      @consumable = consumable
+      @total_consumable_weight = total_consumable_weight
+      @worn = worn
+      @worn_quantity = worn_quantity
+      @total_worn_weight = total_worn_weight
+    end
+
+    alias worn? worn
+
+    alias consumable? consumable
+
+    # Convert to hash
+    #
+    # @return [Hash] Hash representation of the item
+    def to_h
+      {
+        name: name,
+        description: description,
+        weight: weight,
+        total_weight: total_weight,
+        quantity: quantity,
+        image_url: image_url,
+        consumable: consumable,
+        total_consumable_weight: total_consumable_weight,
+        worn: worn,
+        worn_quantity: worn_quantity,
+        total_worn_weight: total_worn_weight
+      }
+    end
+  end
+end

data/lib/packwizard_parser/item_parser.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module PackwizardParser
+  class ItemParser
+    # Parser for extracting a single item row from PackWizard JSON
+    #
+    # @param row [Hash] A single row hash from category['rows']
+    # @return [Item] The parsed item
+    def parse(row)
+      name = extract_name(row)
+      description = extract_description(row)
+
+      weight_per_item = extract_weight(row)
+      quantity = extract_quantity(row)
+
+      image_url = extract_image_url(row)
+
+      consumable = extract_consumable_flag(row)
+      total_consumable_weight = consumable ? weight_per_item * quantity : nil
+
+      # In PackWizard, the returned worn weight is a single items weight regardless of quantity
+      worn = extract_worn_flag(row)
+      worn_quantity = worn ? 1 : 0
+      total_worn_weight = weight_per_item * worn_quantity
+
+      total_weight = weight_per_item * quantity
+
+      Item.new(
+        name: name,
+        description: description,
+        weight: weight_per_item,
+        total_weight: total_weight,
+        quantity: quantity,
+        image_url: image_url,
+        consumable: consumable,
+        total_consumable_weight: total_consumable_weight,
+        worn: worn,
+        worn_quantity: worn_quantity,
+        total_worn_weight: total_worn_weight
+      )
+    end
+
+    private
+
+    def extract_name(row)
+      item_name = row['item']
+      return item_name unless item_name.nil? || item_name.empty?
+
+      'Untitled item'
+    end
+
+    def extract_weight(row)
+      # Extract unit and weight from JSON
+      # If there is a negative value, cancel early and set it to 0.0
+      value = row['weight'].to_f
+      return 0.0 if value <= 0
+
+      unit = row['unit'].to_s.downcase
+
+      # Use module GramConverter to convert the value to grams
+      converted_weight = GramConverter.convert(value: value, unit: unit)
+      return converted_weight if converted_weight
+
+      0.0 # Default value as a fallback
+    end
+
+    def extract_quantity(row)
+      quantity = row['quantity'].to_i
+      return 0 if quantity.negative?
+
+      quantity
+    end
+
+    def extract_worn_flag(row)
+      # weightType 1 for worn items
+      row['weightType'] == 1
+    end
+
+    def extract_consumable_flag(row)
+      # weightType 2 for consumables
+      row['weightType'] == 2
+    end
+
+    def extract_description(row)
+      description = row['description']
+      return description unless description.nil? || description.empty?
+
+      nil
+    end
+
+    def extract_image_url(row)
+      image_url = row['imageUrl']
+      return image_url unless image_url.nil? || image_url.empty?
+
+      nil
+    end
+  end
+end

data/lib/packwizard_parser/list.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module PackwizardParser
+  # Represents a PackWizard list.
+  #
+  # @attr_reader [String] name The name of the list
+  # @attr_reader [String, nil] description Optional description of the list
+  # @attr_reader [Array<Category>] categories Array of categories in this list
+  class List
+    attr_reader :name, :description, :categories
+
+    # @param name [String] The name of the list
+    # @param description [String, nil] Optional description
+    # @param categories [Array<Category>] Array of categories in this list
+    def initialize(name:, description: nil, categories: [])
+      @name = name
+      @description = description
+      @categories = categories
+    end
+
+    # Convert to hash for backward compatibility
+    # @return [Hash] Hash representation of the list
+    def to_h
+      {
+        name: name,
+        description: description,
+        categories: categories.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/packwizard_parser/list_parser.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PackwizardParser
+  # Parser for extracting PackWizard list data from JSON.
+  class ListParser
+    # Extract the lists name and description.
+    # Extract the categories and their items
+    #
+    # @param data [Hash] The fully parsed JSON response.
+    # @param category_parser [CategoryParser] Parser for extracting the categories
+    # @param item_parser [ItemParser] Parser for extracting the items
+    # @return [List] The parsed list
+    def parse(data, category_parser:, item_parser:)
+      List.new(
+        name: extract_name(data),
+        description: extract_description(data),
+        categories: category_parser.parse_all(data, item_parser: item_parser)
+      )
+    end
+
+    private
+
+    def extract_name(data)
+      name = data['packName']
+      return name unless name.nil? || name.empty?
+
+      'Untitled list' # fallback if name is not set
+    end
+
+    def extract_description(data)
+      description = data['packDescription']
+      return description unless description.nil? || description.empty?
+
+      nil
+    end
+  end
+end

data/lib/packwizard_parser/parser.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'httparty'
+require 'json'
+
+module PackwizardParser
+  # Parser for extracting data from PackWizard JSON
+  #
+  # Parser fetches data from the PackWizard API by shareable ID or URL
+  # Accepts full URL or just the ID. In case of full URL insert, we extract the ID and add it to the API_URL.
+  # Delegate parsing to ListParser, CategoryParser, and ItemParser
+  class Parser
+    API_URL = 'https://www.packwizard.com/api/packs/getSharedPackWithId'
+    def initialize(shareable_id:)
+      @shareable_id = extract_id(shareable_id)
+
+      @item_parser = ItemParser.new
+      @category_parser = CategoryParser.new
+      @list_parser = ListParser.new
+    end
+
+    def parse
+      response = HTTParty.get(API_URL, query: { shareableId: @shareable_id }, timeout: 30)
+      raise "Failed to fetch #{response.code}" unless response.success?
+
+      data = JSON.parse(response.body)
+      @list_parser.parse(data, category_parser: @category_parser, item_parser: @item_parser)
+    end
+
+    private
+
+    def extract_id(input)
+      # If the user only inserts the id of the list
+      return input unless input.include?('/')
+
+      # If the user inserts the full url
+      input.split('/').last
+    end
+  end
+end

data/lib/packwizard_parser/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PackwizardParser
+  VERSION = '1.0.0'
+end

data/lib/packwizard_parser.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'packwizard_parser/version'
+require_relative 'packwizard_parser/gram_converter'
+require_relative 'packwizard_parser/item'
+require_relative 'packwizard_parser/category'
+require_relative 'packwizard_parser/list'
+require_relative 'packwizard_parser/item_parser'
+require_relative 'packwizard_parser/category_parser'
+require_relative 'packwizard_parser/list_parser'
+require_relative 'packwizard_parser/parser'
+
+# Parser for extracting data from PackWizard list
+#
+# Provides classes and methods to parse PackWizard list JSON and extract
+# structured data including list information, categories, and items with their
+# properties (weight, quantity, consumable status, etc.).
+module PackwizardParser
+
+  # Convenience method to parse a PackWizard URL
+  def self.parse_url(shareable_id)
+    Parser.new(shareable_id: shareable_id).parse
+  end
+end

data/packwizard-parser.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'lib/packwizard_parser/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'packwizard-parser'
+  spec.version       = PackwizardParser::VERSION
+  spec.authors       = ['Aross AB / Goulight']
+  spec.email         = ['hello@goulight.com']
+
+  spec.summary       = 'Parser for PackWizard lists'
+  spec.description   = 'Parse PackWizard to extract list data including categories, items, weights, and metadata'
+  spec.homepage      = 'https://github.com/goulight/packwizard-parser'
+  spec.license       = 'MIT'
+
+  spec.metadata = {
+    'source_code_uri' => 'https://github.com/goulight/packwizard-parser'
+  }
+
+  spec.required_ruby_version = '>= 3.0'
+
+  spec.files         = Dir['lib/**/*', 'spec/**/*', '*.md', '*.gemspec']
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'httparty', '~> 0.24'
+
+  spec.add_development_dependency 'rspec', '~> 3.13'
+end

data/spec/category_parser_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+RSpec.describe PackwizardParser::CategoryParser do
+  let(:fixture_json) { File.read(File.join(__dir__, 'fixtures', 'tUE6BJs.json')) }
+  let(:data) { JSON.parse(fixture_json) }
+  let(:parser) { described_class.new }
+  let(:item_parser) { PackwizardParser::ItemParser.new }
+
+  describe '#parse_all' do
+    let(:list) { parser.parse_all(data, item_parser: item_parser) }
+
+    it 'extracts the first category' do
+      first_category = list.first
+      expect(first_category.description).to eq('Pack, Tent, Sleep System')
+      expect(first_category.name).to eq('Big 3')
+      expect(first_category.items).to be_a(Array)
+      expect(first_category.items.length).to be > 0
+    end
+  end
+
+  describe 'negative testcases' do
+    let(:fixture_json) { File.read(File.join(__dir__, 'fixtures', 'negative.json')) }
+    let(:data) { JSON.parse(fixture_json) }
+    let(:parser) { described_class.new }
+    let(:item_parser) { PackwizardParser::ItemParser.new }
+    let(:list) { parser.parse_all(data, item_parser: item_parser) }
+
+    it 'extract empty category name' do
+      first_category = list.first
+      expect(first_category.name).to eq('Untitled category')
+    end
+
+    it 'extract empty description' do
+      first_category = list.first
+      expect(first_category.description).to be_nil
+    end
+  end
+end