gold-karat-value 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 34951e42ea5f3c6429d885af49459c464048da0e1ebc6ce220e5fd1c24f9357a
+  data.tar.gz: 61940330e20b042f7184342b1ec56ba5d96c30c739de12ad255e5c59c3911f7f
+SHA512:
+  metadata.gz: 13f3d09187b4b733779638a307dbc3fb23832d2dc4eef4afbb8b7ecb888378cb538adf826c64b06ff990fa3e5b3ee535d6414bffa2427e942361a72d1e26ee98
+  data.tar.gz: aa9504bbdcce04c0148d14cdd1fca79f5fcbdc5569950b10fe5224dea1dda916369948c13c571d67816fb857f59d59ce1a80726e89c6245b03e26aaf322d715f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gold-karat-value contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,60 @@
+# gold-karat-value
+
+Estimate gold melt value from karat, weight, and a 24K price per gram.
+
+Jewelry and scrap workflows usually start from the same three inputs: how heavy the piece is, what karat stamp it carries, and what fine gold is trading at today. This gem keeps that math in one place so a script or backend can reuse the same rounding rules.
+
+It does **not** call a price API. You pass in the 24K price you already have (spot feed, cached quote, or a number typed by the user).
+
+## Install
+
+```ruby
+gem "gold-karat-value", "~> 0.1"
+```
+
+```bash
+gem install gold-karat-value
+```
+
+## Usage
+
+```ruby
+require "gold_karat_value"
+
+melt = GoldKaratValue.melt_value(
+  weight: 10,
+  unit: :gram,
+  karat: 14,
+  price_24k_per_gram: 65
+)
+puts format("14K melt: $%.2f ($%.2f/g)", melt.total, melt.per_gram)
+
+scrap = GoldKaratValue.scrap_value(
+  weight: 10,
+  unit: :gram,
+  karat: 14,
+  price_24k_per_gram: 65,
+  discount: 0.85
+)
+puts format("85%% scrap offer: $%.2f", scrap.scrap)
+```
+
+Units: `:gram`, `:pennyweight`, `:troy_ounce`, `:troy_pound`, `:kilogram`. Karat must be between `0` and `24` (including fractional stamps such as `21.6`).
+
+## Formula
+
+1. Convert the entered weight to grams.
+2. Purity ratio = karat ÷ 24 (14K ≈ 0.5833).
+3. Price per gram at that karat = 24K price per gram × ratio, rounded to cents.
+4. Melt value = grams × that per-gram price, rounded to cents.
+5. Scrap estimate = melt value × a payout ratio between 0 and 1 (for example 0.50 at a pawn shop, 0.85 for some online buyers).
+
+The same cent-rounding is applied to per-gram, per-troy-ounce, and per-troy-pound quotes so table output stays consistent with a UI.
+
+## When you need live prices
+
+This library stops at the arithmetic. If you want the same karat and unit conversion with a regularly updated spot price in the browser, there is a [gold calculator](https://mygoldcalc.com/) that applies these ratios without an account.
+
+## License
+
+MIT

data/lib/gold_karat_value/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GoldKaratValue
+  VERSION = "0.1.0"
+end

data/lib/gold_karat_value.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "gold_karat_value/version"
+
+# Estimate gold melt and scrap value from karat, weight, and a 24K price per gram.
+#
+# This library does not fetch live market data. Pass in a spot price you already
+# have; the helpers convert units, apply karat purity, and round amounts to cents.
+module GoldKaratValue
+  GRAMS_PER_TROY_OUNCE = 31.1035
+  GRAMS_PER_PENNYWEIGHT = 1.55517384
+  GRAMS_PER_TROY_POUND = 373.242
+
+  WEIGHT_TO_GRAMS = {
+    gram: 1.0,
+    pennyweight: GRAMS_PER_PENNYWEIGHT,
+    troy_ounce: GRAMS_PER_TROY_OUNCE,
+    troy_pound: GRAMS_PER_TROY_POUND,
+    kilogram: 1000.0
+  }.freeze
+
+  MeltValue = Struct.new(:total, :per_gram, :per_troy_ounce, :per_troy_pound, keyword_init: true)
+  ScrapValue = Struct.new(:market, :scrap, keyword_init: true)
+
+  class Error < StandardError; end
+  class NegativeWeight < Error; end
+  class InvalidKarat < Error; end
+  class NegativePrice < Error; end
+  class InvalidDiscount < Error; end
+  class UnknownUnit < Error; end
+
+  module_function
+
+  def purity_ratio(karat)
+    karat = Float(karat)
+    raise InvalidKarat, "karat must be between 0 and 24" unless karat.finite? && karat >= 0 && karat <= 24
+
+    karat / 24.0
+  end
+
+  def to_grams(weight, unit)
+    weight = require_non_negative(weight, NegativeWeight)
+    factor = WEIGHT_TO_GRAMS[unit.to_sym]
+    raise UnknownUnit, "unknown unit: #{unit}" unless factor
+
+    weight * factor
+  end
+
+  def round_cents(amount)
+    (Float(amount) * 100.0).round / 100.0
+  end
+
+  def melt_value(weight:, unit:, karat:, price_24k_per_gram:)
+    grams = to_grams(weight, unit)
+    price = require_non_negative(price_24k_per_gram, NegativePrice)
+    per_gram = round_cents(price * purity_ratio(karat))
+
+    MeltValue.new(
+      total: round_cents(grams * per_gram),
+      per_gram: per_gram,
+      per_troy_ounce: round_cents(per_gram * GRAMS_PER_TROY_OUNCE),
+      per_troy_pound: round_cents(per_gram * GRAMS_PER_TROY_POUND)
+    )
+  end
+
+  def scrap_value(weight:, unit:, karat:, price_24k_per_gram:, discount:)
+    discount = Float(discount)
+    raise InvalidDiscount, "discount must be between 0 and 1" unless discount.finite? && discount >= 0 && discount <= 1
+
+    melt = melt_value(
+      weight: weight,
+      unit: unit,
+      karat: karat,
+      price_24k_per_gram: price_24k_per_gram
+    )
+    ScrapValue.new(market: melt.total, scrap: round_cents(melt.total * discount))
+  end
+
+  def require_non_negative(value, error_class)
+    value = Float(value)
+    raise error_class, "value must be finite and non-negative" unless value.finite? && value >= 0
+
+    value
+  end
+  private_class_method :require_non_negative
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: gold-karat-value
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- hiltonlee981
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-08 00:00:00.000000000 Z
+dependencies: []
+description: 'Small Ruby helper for jewelry and scrap workflows: convert weight units,
+  apply karat purity, and round melt/scrap quotes to cents. You supply the 24K spot
+  price.'
+email:
+- hiltonlee981@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/gold_karat_value.rb
+- lib/gold_karat_value/version.rb
+homepage: https://mygoldcalc.com/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://mygoldcalc.com/
+  rubygems_mfa_required: 'false'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Estimate gold melt and scrap value from karat, weight, and a 24K price per
+  gram.
+test_files: []