@le-space/rates 0.1.0 → 0.2.0

package/README.md

@@ -4,6 +4,7 @@ The euro rate of a day, one definition for Le Space's tools – [Belege](https:/
 
 - **a crypto asset: its price at 00:00 UTC of the day** – CoinGecko's daily snapshot; failing that, Kraken's daily candle, its open; before Kraken's candles, Kraken's first trade at or after midnight. With `prefer: 'kraken'` the order turns.
 - **a currency:** the ECB reference rate of the day or the last before it, inverted; RUB after 2022-03-01 from the Bank of Russia, KZT from the National Bank of Kazakhstan, other currencies the Bank of Russia lists as a cross rate through the ruble (marked `cbr-cross`).
+- **Aleph Cloud credits:** priced in USD by Aleph, so no rate of the day: the per-credit price of the last purchase on or before the day, else Aleph's list price (1 USD per 1,000,000 credits), at that day's ECB rate (`aleph-credits`: `alephCreditPrice`, `alephCreditsInEur`).
 - **a token nobody prices:** its deepest Uniswap pool (V2, V3, V4) at the booking's block, against ETH or USDC, through an Alchemy key (`dex-rate`).
 
 Every answer says its source and moment (`{ rate, usdRate, source, at }`), so a document can name them. Rates are decimal strings, never floats.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/rates",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The euro rate of a day for Le Space's tools: the price at 00:00 UTC (CoinGecko, Kraken), the ECB reference rate (Bank of Russia, National Bank of Kazakhstan where it has none), a token's DEX pool at a block. Every answer names its source. Browser and Node; fetch and keys handed in.",
   "license": "AGPL-3.0-or-later",
   "type": "module",
@@ -14,7 +14,8 @@
   "exports": {
     ".": "./src/index.js",
     "./rates": "./src/rates.js",
-    "./dex-rate": "./src/dex-rate.js"
+    "./dex-rate": "./src/dex-rate.js",
+    "./aleph-credits": "./src/aleph-credits.js"
   },
   "files": [
     "src"
@@ -28,7 +29,7 @@
   },
   "dependencies": {
     "@noble/hashes": "2.4.0",
-    "@le-space/ledger": "^0.1.0"
+    "@le-space/ledger": "^0.2.0"
   },
   "devDependencies": {
     "prettier": "3.6.2",

package/src/aleph-credits.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// The euro value of Aleph Cloud credits (Le-Space/belege#113). Credits are
+// no market asset with a rate of the day: Aleph sells them for USD. So a
+// day's consumption is valued at the per-credit price of the last purchase
+// on or before that day, or at Aleph's list price of 1 USD per 1,000,000
+// credits when the account never bought any (credits moved in from another
+// account) – then converted at that day's ECB reference rate
+// (createRateService().rate('USD', day)). A choice for the tax adviser; the
+// statement names it.
+
+import { multiply, normalize } from '@le-space/ledger/decimal';
+
+/** Aleph's list price, USD per credit. */
+export const ALEPH_LIST_PRICE_USD = '0.000001';
+
+/**
+ * The per-credit price in force on each day, from an account's purchases.
+ *
+ * @param {{ time: string, price: string | number | null | undefined }[]} purchases any order; a
+ *   purchase without a price (a transfer in) does not count
+ * @returns {(date: string) => { usdPerCredit: string, source: 'purchase' | 'list' }} date YYYY-MM-DD, UTC
+ */
+export function alephCreditPrice(purchases) {
+	const priced = purchases
+		.filter((p) => p?.price && Number(p.price) > 0)
+		.map((p) => ({ time: String(p.time), price: String(p.price) }))
+		.sort((a, b) => (a.time < b.time ? -1 : 1));
+	return (date) => {
+		let found = null;
+		for (const p of priced) if (p.time.slice(0, 10) <= date) found = p.price;
+		return found
+			? { usdPerCredit: found, source: 'purchase' }
+			: { usdPerCredit: ALEPH_LIST_PRICE_USD, source: 'list' };
+	};
+}
+
+/**
+ * Credits → euros: credits × USD per credit × EUR per USD, rounded half away
+ * from zero to cents. Exact, no float in between.
+ *
+ * @param {string | number} credits
+ * @param {string} usdPerCredit
+ * @param {string} eurPerUsd
+ * @returns {string} EUR, two decimals at most
+ */
+export function alephCreditsInEur(credits, usdPerCredit, eurPerUsd) {
+	const usd = multiply(plain(credits), plain(usdPerCredit), 12);
+	return multiply(usd, plain(eurPerUsd), 2);
+}
+
+/**
+ * A number as a plain decimal string (no exponent), at most 12 decimals.
+ *
+ * @param {string | number} v
+ */
+export function plain(v) {
+	if (typeof v === 'string' && /^-?\d+(\.\d+)?$/.test(v)) return normalize(v);
+	const n = Number(v);
+	if (!Number.isFinite(n)) throw new Error(`not a number: ${v}`);
+	return normalize(n.toFixed(12));
+}

package/src/index.js

@@ -4,7 +4,8 @@
 // trade at or after midnight), the ECB reference rate for currencies (Bank of
 // Russia, National Bank of Kazakhstan where the ECB has none), and a token's
 // DEX pool at the booking's block where nobody prices it. Every answer names
-// its source and moment. `fetch` and the keys are handed in.
+// its source and moment. `fetch` and the keys are handed in. Aleph Cloud
+// credits, priced in USD by Aleph, have their own rule (aleph-credits.js).
 export {
 	CBR_CROSS_CURRENCIES,
 	COINGECKO_PLATFORMS,
@@ -26,3 +27,9 @@ export {
 	v4PoolId,
 	virtualReserve
 } from './dex-rate.js';
+export {
+	ALEPH_LIST_PRICE_USD,
+	alephCreditPrice,
+	alephCreditsInEur,
+	plain
+} from './aleph-credits.js';