{"_id":"@agaudeals/premium-calc","name":"@agaudeals/premium-calc","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agaudeals/premium-calc","version":"0.1.0","description":"Compute precious-metal dealer premiums (per-oz, percent, per-gram-pure) from spot price, dealer price, weight, and purity. Pure function, zero runtime dependencies.","keywords":["gold","silver","platinum","palladium","spot-price","premium","bullion","numismatic","agaudeals"],"license":"MIT","author":{"name":"AgAu Deals","email":"hello@agaudeals.com"},"homepage":"https://agaudeals.com","repository":{"type":"git","url":"git+https://github.com/agaudeals/agaudeals-js.git","directory":"packages/premium-calc"},"bugs":{"url":"https://github.com/agaudeals/agaudeals-js/issues"},"type":"module","main":"./dist/cjs/index.cjs","module":"./dist/esm/index.js","types":"./dist/types/index.d.ts","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.cjs"}},"engines":{"node":">=20.0.0"},"scripts":{"clean":"rm -rf dist","build:esm":"tsc -p tsconfig.esm.json","build:cjs":"tsc -p tsconfig.cjs.json && node ../../scripts/rename-cjs.mjs dist/cjs","build:types":"tsc -p tsconfig.types.json","build":"npm run clean && npm run build:esm && npm run build:cjs && npm run build:types","typecheck":"tsc -p tsconfig.json --noEmit","test":"node --test --import tsx test/*.test.ts"},"devDependencies":{"tsx":"^4.7.0"},"publishConfig":{"access":"public"},"_id":"@agaudeals/premium-calc@0.1.0","gitHead":"2441ce387f6f30ae131f20876cc2c9133d501ab9","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-5XBC2cSI4yrzeRhOmqpKufZ5hgF4QZe95CsxWcLWTf9uQJK7BYDC9MfBYhMx9acewxtu5Bij/MwJGUf/imml2A==","shasum":"2303546fa7e281b6d02148858be88fd63d6f22ab","tarball":"https://registry.npmjs.org/@agaudeals/premium-calc/-/premium-calc-0.1.0.tgz","fileCount":9,"unpackedSize":11057,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agaudeals%2fpremium-calc@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCJae3TlSW3Mi6PyDYLjLj7mtq6+uSw3tsaThOWRvNTcgIhANRYhmqLLgRPCJucUWHxVdjDstcUwbV/BHX4C/BCtZmH"}]},"_npmUser":{"name":"agaudeals-dev","email":"agaudeals@gmail.com"},"directories":{},"maintainers":[{"name":"agaudeals-dev","email":"agaudeals@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/premium-calc_0.1.0_1777827096582_0.9555326578215826"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-03T16:51:36.480Z","0.1.0":"2026-05-03T16:51:36.766Z","modified":"2026-05-03T16:51:37.172Z"},"maintainers":[{"name":"agaudeals-dev","email":"agaudeals@gmail.com"}],"description":"Compute precious-metal dealer premiums (per-oz, percent, per-gram-pure) from spot price, dealer price, weight, and purity. Pure function, zero runtime dependencies.","homepage":"https://agaudeals.com","keywords":["gold","silver","platinum","palladium","spot-price","premium","bullion","numismatic","agaudeals"],"repository":{"type":"git","url":"git+https://github.com/agaudeals/agaudeals-js.git","directory":"packages/premium-calc"},"author":{"name":"AgAu Deals","email":"hello@agaudeals.com"},"bugs":{"url":"https://github.com/agaudeals/agaudeals-js/issues"},"license":"MIT","readme":"# @agaudeals/premium-calc\n\n[![npm version](https://img.shields.io/npm/v/@agaudeals/premium-calc.svg)](https://www.npmjs.com/package/@agaudeals/premium-calc)\n[![license](https://img.shields.io/npm/l/@agaudeals/premium-calc.svg)](./LICENSE)\n[![CI](https://github.com/agaudeals/agaudeals-js/actions/workflows/ci.yml/badge.svg)](https://github.com/agaudeals/agaudeals-js/actions/workflows/ci.yml)\n\nCompute precious-metal dealer premiums (per-oz, percent, per-gram-pure, per-oz-pure) from a spot price, dealer price, weight, and purity. Pure function, **zero runtime dependencies**, full TypeScript types. Part of [agaudeals.com](https://agaudeals.com).\n\n## Install\n\n```sh\nnpm install @agaudeals/premium-calc\n```\n\nRequires Node 20+. ESM and CJS entries.\n\n## Quick start\n\n```ts\nimport { computePremium } from '@agaudeals/premium-calc';\n\n// American Silver Eagle: 1 oz, .999 fine, dealer asking $32 over $25 spot.\nconst r = computePremium({\n  spotUsdPerOz: 25,\n  dealerPriceUsd: 32,\n  weightTroyOz: 1,\n  purity: 0.999,\n});\n\nconsole.log(r);\n// {\n//   premiumPerOz: 7.032...,\n//   premiumPct: 28.13...,\n//   pricePerGramPure: 1.029...,\n//   pricePerOzPure: 32.032...,\n// }\n```\n\n## API\n\n### `computePremium(input) → result`\n\n```ts\ninterface ComputePremiumInput {\n  spotUsdPerOz: number;     // > 0\n  dealerPriceUsd: number;   // > 0; total ask for the lot\n  weightTroyOz: number;     // > 0; per-unit gross weight\n  purity: number;           // (0, 1]; e.g. 0.999, 0.9167, 0.9\n  quantity?: number;        // > 0; defaults to 1\n}\n\ninterface ComputePremiumResult {\n  premiumPerOz: number;     // pricePerOzPure − spot\n  premiumPct: number;       // (premiumPerOz / spot) * 100\n  pricePerGramPure: number; // dealer / (totalPureOz * 31.1034768)\n  pricePerOzPure: number;   // dealer / (weight * purity * quantity)\n}\n```\n\n`TROY_OZ_GRAMS` (`31.1034768`) is exported for callers that want to convert independently.\n\n## Worked example: feeding `@agaudeals/spot-price` into `premium-calc`\n\n```ts\nimport { SpotPrice } from '@agaudeals/spot-price';\nimport { computePremium } from '@agaudeals/premium-calc';\n\nconst spot = new SpotPrice(); // Stooq, 60s cache\n\n// Listing under evaluation: 1 kg gold bar (32.1507 troy oz, .9999 fine), $65,000 ask.\nconst xau = await spot.getSpot('XAU');\nconst result = computePremium({\n  spotUsdPerOz: xau.priceUsdPerOz,\n  dealerPriceUsd: 65_000,\n  weightTroyOz: 32.1507,\n  purity: 0.9999,\n});\n\nconsole.log(`Spot: $${xau.priceUsdPerOz.toFixed(2)}/oz (source: ${xau.source}, stale: ${xau.stale})`);\nconsole.log(`Premium: $${result.premiumPerOz.toFixed(2)}/oz pure (${result.premiumPct.toFixed(2)}%)`);\n```\n\n## Validation\n\nAny of the following throws `RangeError` with a message naming the bad field:\n\n- `spotUsdPerOz`, `dealerPriceUsd`, `weightTroyOz`, `quantity` — must be finite and `> 0`\n- `purity` — must be finite and in `(0, 1]`\n\n```ts\ncomputePremium({ spotUsdPerOz: 2000, dealerPriceUsd: 2100, weightTroyOz: 1, purity: 1.5 });\n// → RangeError: purity must be in (0, 1], got 1.5\n```\n\n## Out of scope (v0.1)\n\n- Multi-currency (USD only — wrap with your FX layer if needed).\n- Comparison/ranking helpers across listings (deferred to v1.0).\n\n## License\n\nMIT — see [LICENSE](./LICENSE). Maintained by [AgAu Deals](https://agaudeals.com).\n","readmeFilename":"README.md","_rev":"1-236e09e4d6eb8b31a112ddef048dbd70"}