uae-gold-calculator 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a7d280f92d142e15ab21616135e1ca094a384cbcf3503a4ca9f4d63ed62e7704
+  data.tar.gz: 3c443bccbe540f53e87067b0421150222a492b437b5d92ec35226f439b1f1d7d
+SHA512:
+  metadata.gz: 0576f2eb658146d1700e9eb393957cef924c85250d2ed5f3187b49a45f3705f3d24c1bf175571704e37ed29a423a98decd09da7a8b0d379498acd175ab786a45
+  data.tar.gz: b052de66bce06d27c3544e3fd65c7f279481cca3fe67bc7a7c8f99bcc576e6e53526a82653e5940bcec6a0fc2e410844aadd24f8ee29fe5745bc47a9a25a4c1f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UAE Gold Prices (https://uaegoldprices.ae/)
+
+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,79 @@
+# uae-gold-calculator
+
+Gold value calculator for the UAE market. Give it today's 24K price per gram and it works out every karat, any weight unit, the making charge, 5% VAT and zakat, in Arabic or English. No network calls, no dependencies.
+
+- **Karat table**: 24K, 22K, 21K, 18K and 14K per gram, per tola and per troy ounce using the fineness UAE price boards quote: 24K 999, 22K 914, 21K 874, 18K 749, 14K 583 (karat price = 24K price × fineness ÷ 999).
+- **Units**: gram, kilogram, troy ounce (31.1034768 g), tola (11.6638038 g) and mithqal (4.25 g). Arabic unit names such as `جرام`, `أونصة`, `تولة`, `مثقال` work too.
+- **Jewellery price**: metal value + making charge (AED per gram, percent of metal, or a fixed amount) + VAT on both, the way UAE shops bill it.
+- **Zakat**: adds up pure gold across items, compares it with the 85 g nisab and returns 2.5% of the value when due.
+- **Friendly input**: `461.11`, `461,11`, `14,342.21` and Arabic-Indic `٤٦١٫١١` all parse.
+- **Arabic and English** CLI output (`--lang ar`).
+
+## Install
+
+```
+gem install uae-gold-calculator
+```
+
+## Library
+
+```ruby
+require "uae_gold_calculator"
+G = UaeGoldCalculator
+
+G.price_table(461.11)[2][:per_gram]                                  # => 403.41 (21K)
+G.item_price(price24: 461.11, weight: 10, karat: 21, making: 30)[:total] # => 4550.84
+G.zakat(461.11, [{ weight: 100, karat: 21 }])[:zakat]                # => 1008.53
+G.parse_number("٤٦١٫١١")                                             # => 461.11
+```
+
+## CLI
+
+```
+$ uae-gold-calculator table --price 461.11
+Karat	Per gram	Per tola	Per ounce
+24K (999)	461.11	5378.30	14342.12
+22K (914)	421.88	4920.68	13121.82
+21K (874)	403.41	4705.34	12547.56
+18K (749)	345.72	4032.38	10753.00
+14K (583)	269.10	3138.69	8369.83
+
+$ uae-gold-calculator item --price 461.11 --weight 10 --karat 21 --making 30 --lang ar
+قيمة الذهب: 4034.14 د.إ
+المصنعية: 300.00 د.إ
+ضريبة القيمة المضافة (5%): 216.71 د.إ
+الإجمالي: 4550.84 د.إ
+
+$ uae-gold-calculator convert 2 tola g
+23.3276
+
+$ uae-gold-calculator zakat --price 461.11 --weight 100 --karat 21
+Zakat due: 1008.53 AED
+```
+
+Options for `item`: `--unit g|kg|oz|tola|mithqal`, `--karat`, `--making`, `--making-type per_gram|percent|fixed`, `--vat 0.05` (use `--vat 0` for investment bars, which are zero-rated in the UAE).
+
+## How it calculates
+
+| Step | Formula |
+|---|---|
+| Karat price per gram | `price24 × fineness / 999` (24K 999, 22K 914, 21K 874, 18K 749, 16K 666, 14K 583; other karats `karat / 24`) |
+| Metal value | `grams × karat price` |
+| Making charge | `rate × grams`, or `metal × rate / 100`, or a fixed amount |
+| VAT | `(metal + making) × 5%` |
+| Zakat | `24K-equivalent grams = Σ grams × purity`; due when ≥ 85 g; `2.5% × pure grams × price24` |
+
+Amounts are rounded half away from zero to 2 decimals on output only. Results are estimates: shop prices, VAT treatment of investment gold and zakat rulings vary, so check with your jeweller or scholar.
+
+## بالعربية
+
+حاسبة لقيمة الذهب في الإمارات: أدخل سعر جرام الذهب عيار 24 اليوم لتحصل على أسعار عيارات 24 و22 و21 و18 و14 بالجرام والتولة والأونصة، وسعر قطعة المجوهرات مع المصنعية وضريبة القيمة المضافة 5%، وحساب زكاة الذهب حسب نصاب 85 جرامًا. تقبل الأرقام العربية مثل ٤٦١٫١١ وأسماء الوحدات بالعربية، وتعمل دون اتصال بالإنترنت.
+
+## Links
+
+- Live UAE gold rates: [سعر الذهب اليوم في الامارات](https://uaegoldprices.ae/)
+- Source code: https://github.com/nbkdevs/uae-gold-prices
+
+## License
+
+MIT © UAE Gold Prices

data/exe/uae-gold-calculator

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "uae_gold_calculator"
+
+G = UaeGoldCalculator
+pos = []
+opt = {}
+i = 0
+while i < ARGV.length
+  if ARGV[i].start_with?("--")
+    opt[ARGV[i][2..]] = ARGV[i + 1]
+    i += 2
+  else
+    pos << ARGV[i]
+    i += 1
+  end
+end
+ar = opt["lang"] == "ar"
+cur = ar ? "د.إ" : "AED"
+begin
+  case pos.first
+  when "convert"
+    puts G.round_money(G.convert(pos[1], pos[2], pos[3]), 4)
+  when "table"
+    puts(ar ? "العيار\tسعر الجرام\tسعر التولة\tسعر الأونصة" : "Karat\tPer gram\tPer tola\tPer ounce")
+    G.price_table(opt.fetch("price")).each do |r|
+      puts format("%dK (%d)\t%.2f\t%.2f\t%.2f", r[:karat], r[:hallmark], r[:per_gram], r[:per_tola], r[:per_ounce])
+    end
+  when "item"
+    r = G.item_price(price24: opt.fetch("price"), weight: opt.fetch("weight"), unit: opt.fetch("unit", "g"),
+                     karat: G.parse_number(opt.fetch("karat", "24")), making: opt.fetch("making", "0"),
+                     making_type: opt.fetch("making-type", "per_gram"), vat_rate: opt.fetch("vat", "0.05"))
+    puts format("%s: %.2f %s", ar ? "قيمة الذهب" : "Gold value", r[:metal], cur)
+    puts format("%s: %.2f %s", ar ? "المصنعية" : "Making charge", r[:making], cur)
+    puts format("%s: %.2f %s", ar ? "ضريبة القيمة المضافة" : "VAT", r[:vat], cur)
+    puts format("%s: %.2f %s", ar ? "الإجمالي" : "Total", r[:total], cur)
+  when "zakat"
+    z = G.zakat(opt.fetch("price"), [{ weight: opt.fetch("weight"), unit: opt.fetch("unit", "g"),
+                                        karat: G.parse_number(opt.fetch("karat", "24")) }])
+    puts(z[:due] ? format("%s: %.2f %s", ar ? "الزكاة المستحقة" : "Zakat due", z[:zakat], cur) : (ar ? "أقل من النصاب: لا زكاة" : "Below nisab: no zakat due"))
+  else
+    puts "uae-gold-calculator #{G::VERSION}: table | item | convert | zakat. Today's 24K price: https://uaegoldprices.ae/"
+  end
+rescue KeyError, ArgumentError => e
+  warn "Error: #{e.message}"
+  exit 1
+end

data/lib/uae_gold_calculator.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# Gold value maths for the UAE market: karat prices, unit conversion, making
+# charges, VAT and zakat. Pure Ruby, no network. Pass today's 24K price per
+# gram (for example from https://uaegoldprices.ae/).
+module UaeGoldCalculator
+  VERSION = "1.0.0"
+  KARATS = [24, 22, 21, 18, 14].freeze
+  # Fineness per mille used by UAE gold price boards (and uaegoldprices.ae).
+  # A karat's price = 24K price x fineness / 999; other karats use karat / 24.
+  HALLMARKS = { 24 => 999, 22 => 914, 21 => 874, 18 => 749, 16 => 666, 14 => 583 }.freeze
+  UNITS = { "g" => 1.0, "kg" => 1000.0, "oz" => 31.1034768, "tola" => 11.6638038, "mithqal" => 4.25 }.freeze
+  ALIASES = {
+    "gram" => "g", "grams" => "g", "gr" => "g", "جرام" => "g", "غرام" => "g",
+    "kilogram" => "kg", "kilo" => "kg", "كيلو" => "kg",
+    "ounce" => "oz", "ozt" => "oz", "troy_ounce" => "oz", "troy-ounce" => "oz", "أونصة" => "oz", "اونصة" => "oz",
+    "tolas" => "tola", "تولة" => "tola", "mithqals" => "mithqal", "misqal" => "mithqal", "مثقال" => "mithqal"
+  }.freeze
+  UAE_VAT_RATE = 0.05
+  NISAB_GRAMS = 85.0
+  ZAKAT_RATE = 0.025
+
+  module_function
+
+  # Round half away from zero.
+  def round_money(x, dp = 2)
+    f = 10.0**dp
+    v = ((x.abs * f) + 1e-9).round / f
+    x.negative? ? -v : v
+  end
+
+  # Parse "461.11", "461,11", "14,342.21" or Arabic-Indic "٤٦١٫١١".
+  def parse_number(value)
+    return value.to_f if value.is_a?(Numeric)
+
+    s = value.to_s.strip.tr("٠١٢٣٤٥٦٧٨٩۰۱۲۳۴۵۶۷۸۹٫", "01234567890123456789.").delete("٬").gsub(/\s/, "")
+    s = s.match?(/\A\d{1,3}(,\d{3})+(\.\d+)?\z/) ? s.delete(",") : s.sub(",", ".")
+    Float(s)
+  rescue ArgumentError, TypeError
+    raise ArgumentError, "not a number: #{value}"
+  end
+
+  def normalize_unit(unit)
+    u = (unit || "g").to_s.strip.downcase
+    k = ALIASES.fetch(u, u)
+    raise ArgumentError, "unknown unit: #{unit}. Use g, kg, oz, tola or mithqal" unless UNITS.key?(k)
+
+    k
+  end
+
+  def check(name, v, allow_zero: false)
+    if !v.finite? || v.negative? || (!allow_zero && v.zero?)
+      raise ArgumentError, "#{name} must be #{allow_zero ? 'non-negative' : 'positive'}"
+    end
+
+    v
+  end
+
+  def purity(karat)
+    k = karat.to_f
+    raise ArgumentError, "karat must be between 0 and 24" unless k.positive? && k <= 24
+    return 1.0 if k == 24
+
+    f = k == k.floor ? HALLMARKS[k.to_i] : nil
+    f ? f / 999.0 : k / 24
+  end
+
+  def convert(value, from, to)
+    check("value", parse_number(value), allow_zero: true) * UNITS[normalize_unit(from)] / UNITS[normalize_unit(to)]
+  end
+
+  def karat_price(price24, karat)
+    check("price24", parse_number(price24)) * purity(karat)
+  end
+
+  def price_table(price24)
+    KARATS.map do |k|
+      g = karat_price(price24, k)
+      { karat: k, hallmark: HALLMARKS[k], per_gram: round_money(g),
+        per_tola: round_money(g * UNITS["tola"]), per_ounce: round_money(g * UNITS["oz"]) }
+    end
+  end
+
+  def item_price(price24:, weight:, unit: "g", karat: 24, making: 0, making_type: :per_gram, vat_rate: UAE_VAT_RATE)
+    grams = check("weight", parse_number(weight)) * UNITS[normalize_unit(unit)]
+    per_gram = karat_price(price24, karat)
+    metal = grams * per_gram
+    m = check("making", parse_number(making), allow_zero: true)
+    mk = case making_type.to_sym
+         when :per_gram then m * grams
+         when :percent then metal * m / 100
+         when :fixed then m
+         else raise ArgumentError, "making_type must be per_gram, percent or fixed"
+         end
+    rate = check("vat_rate", parse_number(vat_rate), allow_zero: true)
+    sub = metal + mk
+    { grams: round_money(grams, 4), price_per_gram: round_money(per_gram), metal: round_money(metal),
+      making: round_money(mk), subtotal: round_money(sub), vat_rate: rate, vat: round_money(sub * rate),
+      total: round_money(sub + (sub * rate)) }
+  end
+
+  # items: [{ weight: 100, karat: 21, unit: "g" }]
+  def zakat(price24, items)
+    p = check("price24", parse_number(price24))
+    pure = items.sum do |it|
+      check("weight", parse_number(it[:weight]), allow_zero: true) * UNITS[normalize_unit(it[:unit])] * purity(it.fetch(:karat, 24))
+    end
+    value = pure * p
+    due = pure + 1e-9 >= NISAB_GRAMS
+    { pure_grams: round_money(pure, 4), value: round_money(value), nisab_value: round_money(NISAB_GRAMS * p),
+      due: due, zakat: due ? round_money(value * ZAKAT_RATE) : 0.0 }
+  end
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: uae-gold-calculator
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- UAE Gold Prices
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Price gold in AED from today''s 24K rate: 24/22/21/18/14K per gram,
+  tola and troy ounce, making charges (per gram, percent or fixed), 5% VAT and zakat
+  against the 85 g nisab. Accepts Arabic-Indic digits and Arabic unit names. Library
+  + CLI, no dependencies.'
+executables:
+- uae-gold-calculator
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/uae-gold-calculator
+- lib/uae_gold_calculator.rb
+homepage: https://uaegoldprices.ae/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://uaegoldprices.ae/
+  source_code_uri: https://github.com/nbkdevs/uae-gold-prices
+  bug_tracker_uri: https://github.com/nbkdevs/uae-gold-prices/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'Gold value calculator for the UAE: karat prices, making charges, 5% VAT
+  and zakat.'
+test_files: []