@ducatjs/money 0.0.0 → 0.2.0

package/data/klarna.json

@@ -0,0 +1,95 @@
+{
+  "processor": "Klarna",
+  "retrieved": "2026-11-07",
+  "amountFormat": "integer",
+  "sources": {
+    "dataTypes": {
+      "url": "https://docs.klarna.com/acquirer/klarna/get-started/integration-resilience/data-types/",
+      "quotes": [
+        "We express amounts in minor units according to the ISO 4217 standard. That means they are expressed in the smallest unit of currency. Examples are USD with 1000 representing USD GBP 10, with 500 representing GBP EUR 5, with 50 representing EUR 0.50 and SEK with 100 representing 1kr.",
+        "{\"order_amount\": 1000}"
+      ]
+    },
+    "countries": {
+      "url": "https://docs.klarna.com/klarna-payments/in-depth-knowledge/puchase-countries-currencies-locales/",
+      "quotes": [
+        "We only support the local currency of each country.",
+        "The following table shows the list of available countries, locales, and currencies for Klarna payments."
+      ]
+    },
+    "api": {
+      "url": "https://docs.klarna.com/acquirer/klarna/api/payments/",
+      "quotes": [
+        "order_amount: {\"type\": \"integer\", \"format\": \"int64\", \"example\": 2000, \"minimum\": 0} Total amount of the order including tax and any available discounts. The value should be in non-negative minor units. Eg: 25 Euros should be 2500.",
+        "order_lines[].total_amount: Total amount of the order line. Must be defined as minor units. Includes tax and discount. Eg: 2000=20 euros\nValue = (quantity x unit_price) - total_discount_amount. \n(max value: 200000000)",
+        "order_lines[].tax_rate: {\"type\": \"integer\", \"minimum\": 0, \"maximum\": 10000} Tax rate of the order line. Non-negative value. The percentage value is represented with two implicit decimals. I.e 2000 = 20%.",
+        "purchase_currency: The purchase currency of the order. Formatted according to ISO 4217 standard, e.g. USD, EUR, SEK, GBP, etc.",
+        "order_lines[].total_tax_amount: Total tax amount of the order line. Must be within ±1 of total_amount - total_amount 10000 / (10000 + tax_rate). Negative when type is discount.",
+        "order_lines[].unit_price: Price for a single unit of the order line. Must be defined as minor units and exclude any discount."
+      ]
+    }
+  },
+  "defaultExponent": "iso",
+  "currencies": [
+    "AUD",
+    "CAD",
+    "CHF",
+    "CZK",
+    "DKK",
+    "EUR",
+    "GBP",
+    "HUF",
+    "MXN",
+    "NOK",
+    "NZD",
+    "PLN",
+    "RON",
+    "SEK",
+    "USD"
+  ],
+  "countryCurrency": {
+    "AU": "AUD",
+    "AT": "EUR",
+    "BE": "EUR",
+    "CA": "CAD",
+    "CZ": "CZK",
+    "DK": "DKK",
+    "FI": "EUR",
+    "FR": "EUR",
+    "DE": "EUR",
+    "GR": "EUR",
+    "HU": "HUF",
+    "IE": "EUR",
+    "IT": "EUR",
+    "MX": "MXN",
+    "NL": "EUR",
+    "NZ": "NZD",
+    "NO": "NOK",
+    "PL": "PLN",
+    "PT": "EUR",
+    "RO": "RON",
+    "SK": "EUR",
+    "ES": "EUR",
+    "SE": "SEK",
+    "CH": "CHF",
+    "GB": "GBP",
+    "US": "USD"
+  },
+  "notes": [
+    "Amounts are integers in ISO 4217 minor units for every supported currency; all 15 are two-decimal in ISO, so HUF is in fillér (1000 HUF = 100000), unlike PayPal (HUF takes no decimals).",
+    "The data-types sentence is quoted as published; its examples read: USD 1000 = USD 10, GBP 500 = GBP 5, EUR 50 = EUR 0.50, SEK 100 = 1 kr.",
+    "Each purchase country has exactly one currency; the pairing is not checked by ducat.",
+    "Limits (order_amount >= 0; an order line's total_amount at most 200000000) are not enforced by ducat.",
+    "Signs: order_amount, order_tax_amount and total_discount_amount have minimum 0; order-line unit_price and total_amount have no minimum, and total_tax_amount is negative for discount lines. toKlarna therefore passes negative amounts through."
+  ],
+  "unverified": [
+    {
+      "claim": "HUF is sent in fillér (2 decimals, per the ISO 4217 statement); no Klarna page gives a HUF example.",
+      "verified": false
+    },
+    {
+      "claim": "Captures and refunds (Order Management API) use the same integer minor units (the reference page renders its schema client-side; only the Payments schema was read).",
+      "verified": false
+    }
+  ]
+}

package/data/paypal.json

@@ -0,0 +1,65 @@
+{
+  "processor": "PayPal",
+  "retrieved": "2026-11-07",
+  "amountFormat": "decimal-string",
+  "sources": {
+    "currencies": {
+      "url": "https://developer.paypal.com/api/rest/reference/currency-codes/",
+      "lastUpdated": "2026-08-17",
+      "quotes": [
+        "This currency does not support decimals. If you pass a decimal amount, an error occurs.",
+        "This currency is supported as a payment currency and a currency balance for in-country PayPal accounts only. If the receiver of funds is not from Brazil, then PayPal converts funds into the primary holding currency of the account with the applicable currency conversion rate. The currency conversion rate includes PayPal's applicable spread or fee.",
+        "This currency is supported as a payment currency and a currency balance for in-country PayPal accounts only."
+      ]
+    },
+    "currencyReference": {
+      "url": "https://developer.paypal.com/reference/currency-codes/",
+      "lastUpdated": "2026-08-17",
+      "quotes": [
+        "Zero-digit currency — no decimal places or fractions",
+        "This currency is supported as a payment currency (buyer currency) or settlement currency (holding currency) only for in-country PayPal accounts. If the settlement account is based outside the country, PayPal converts money into the account's primary currency with the applicable currency conversion rate, which includes a spread or fee."
+      ]
+    },
+    "orders": {
+      "url": "https://developer.paypal.com/api/orders/v2/schema.yaml",
+      "quotes": [
+        "money.value: The value, which might be: An integer for currencies like `JPY` that are not typically fractional. A decimal fraction for currencies like `TND` that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.",
+        "money.value: {\"type\": \"string\", \"minLength\": 0, \"maxLength\": 32, \"pattern\": \"^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$\"}",
+        "The amount must be a positive number. The `amount.value` field supports up to 15 digits preceding the decimal.",
+        "Create Order - Minimal Request and Response: {\"currency_code\": \"USD\", \"value\": \"100.00\"}",
+        "amount {\"currency_code\": \"USD\", \"value\": \"230.00\"}, breakdown item_total \"220.00\", shipping \"10.00\"; items unit_amount \"20.00\" x quantity \"1\" and \"100.00\" x quantity \"2\""
+      ]
+    }
+  },
+  "defaultExponent": "iso",
+  "exponents": {
+    "HUF": 0,
+    "JPY": 0,
+    "TWD": 0
+  },
+  "currencies": [
+    "AUD", "BRL", "CAD", "CHF", "CNY", "CZK", "DKK", "EUR", "GBP", "HKD", "HUF", "ILS", "JPY",
+    "MXN", "MYR", "NOK", "NZD", "PHP", "PLN", "RUB", "SEK", "SGD", "THB", "TWD", "USD"
+  ],
+  "inCountryOnly": ["BRL", "CNY", "MYR"],
+  "notes": [
+    "The amount is a decimal string in major units. HUF and TWD (ISO 2 decimals) and JPY must be whole numbers; every other listed currency is two-decimal, as in ISO 4217.",
+    "The Orders schema mentions TND (three decimals) as an example, but TND is not on either currency page, so it is not accepted here.",
+    "The two currency pages disagree: the REST reference page (linked from the Orders schema) lists RUB; the general reference page does not.",
+    "The schema pattern allows a leading minus and a bare fraction such as \".5\"; the text says the amount must be positive. ducat emits a leading 0 and does not enforce the sign."
+  ],
+  "unverified": [
+    {
+      "claim": "A zero fraction such as \"100.00\" for JPY, HUF or TWD is rejected (the page says only that a decimal amount is an error). toPayPal always sends whole numbers for these.",
+      "verified": false
+    },
+    {
+      "claim": "RUB is still accepted (listed on the REST reference page only).",
+      "verified": false
+    },
+    {
+      "claim": "Payouts use the same currency rules (no Payouts-specific currency page was found).",
+      "verified": false
+    }
+  ]
+}

package/data/stripe-fx.json

@@ -0,0 +1,17 @@
+{
+  "source": "https://docs.stripe.com/api/balance_transactions/object",
+  "retrieved": "2026-11-07",
+  "quotes": {
+    "exchange_rate": "If applicable, this transaction uses an exchange rate. If money converts from currency A to currency B, then the `amount` in currency A, multiplied by the `exchange_rate`, equals the `amount` in currency B. For example, if you charge a customer 10.00 EUR, the PaymentIntent's `amount` is `1000` and `currency` is `eur`. If this converts to 12.34 USD in your Stripe account, the BalanceTransaction's `amount` is `1234`, its `currency` is `usd`, and the `exchange_rate` is `1.234`.",
+    "amount": "Gross amount of this transaction (in the smallest currency unit). A positive value represents funds charged to another party, and a negative value represents funds sent to another party.",
+    "currency": "Three-letter ISO currency code, in lowercase. Must be a supported currency.",
+    "created": "Time at which the object was created. Measured in seconds since the Unix epoch."
+  },
+  "notes": [
+    "exchange_rate is a nullable JSON number; null when no conversion happened.",
+    "No rounding rule for conversions is documented on this page or on https://docs.stripe.com/currencies/conversions."
+  ],
+  "vectors": [
+    { "charge": { "amount": 1000, "currency": "eur" }, "balanceTransaction": { "amount": 1234, "currency": "usd", "exchange_rate": 1.234 } }
+  ]
+}

package/data/stripe.json

@@ -0,0 +1,285 @@
+{
+  "source": "https://docs.stripe.com/currencies",
+  "retrieved": "2026-11-07",
+  "notes": [
+    "Currencies are two-decimal unless listed below (\"Currencies are two-decimal currencies unless otherwise specified.\").",
+    "Live page: \"This list contains zero-decimal currencies that have general API support.\" Same list as the embedded zero_decimal array. ISK is NOT in it (special case, two-decimal representation).",
+    "No three-decimal section on the live page; list from archived 2024 version (matches the five codes that the live embedded data offers only to AE accounts).",
+    "Stripe requires lowercase currency codes in API requests."
+  ],
+  "defaultExponent": 2,
+  "zeroDecimal": [
+    "BIF",
+    "CLP",
+    "DJF",
+    "GNF",
+    "JPY",
+    "KMF",
+    "KRW",
+    "MGA",
+    "PYG",
+    "RWF",
+    "UGX",
+    "VND",
+    "VUV",
+    "XAF",
+    "XOF",
+    "XPF"
+  ],
+  "threeDecimal": [
+    "BHD",
+    "JOD",
+    "KWD",
+    "OMR",
+    "TND"
+  ],
+  "specialCases": {
+    "ISK": {
+      "apiExponent": 2,
+      "rule": "Charges: amount in hundredths, decimal part always 00 (amount % 100 == 0). No fractional ISK.",
+      "quote": "ISK transitioned to a zero-decimal currency, but backward compatibility requires you to represent it as a two-decimal value, where the decimal amount is always 00. For example, to charge 5 ISK, provide an amount value of 500. You can’t charge fractions of ISK."
+    },
+    "HUF": {
+      "apiExponent": 2,
+      "rule": "Charges may use two decimals; manual payouts must be integer amounts evenly divisible by 100 (whole forints).",
+      "quote": "Stripe treats HUF as a zero-decimal currency for payouts, even though you can charge two-decimal amounts. When you create a manual payout in HUF, you must provide integer amounts that are evenly divisible by 100. For example, if you have an available balance of HUF 10.45, you can pay out HUF 10 by submitting 1000 for the amount value. You can’t submit a payout for the full balance, HUF 10.45, because the amount value of 1045 isn’t evenly divisible by 100."
+    },
+    "TWD": {
+      "apiExponent": 2,
+      "rule": "Charges may use two decimals; manual payouts must be integer amounts evenly divisible by 100 (whole dollars).",
+      "quote": "Stripe treats TWD as a zero-decimal currency for payouts, even though you can charge two-decimal amounts. When you create a manual payout in TWD, you must provide integer amounts that are evenly divisible by 100. For example, if you have an available balance of TWD 800.45, you can pay out TWD 800 by submitting 80000 for the amount value. You can’t submit a payout for the full balance, TWD 800.45, because the amount value of 80045 isn’t evenly divisible by 100."
+    },
+    "UGX": {
+      "apiExponent": 2,
+      "rule": "Amount in hundredths, decimal part always 00 (amount % 100 == 0); invoices with fractional amounts are rounded to nearest multiple of 100 and the difference goes to the customer balance.",
+      "quote": "UGX transitioned to a zero-decimal currency, but backwards compatibility requires you to represent it as a two-decimal value, where the decimal amount is always 00. For example, to charge 5 UGX, provide an amount value of 500. You can’t charge fractions of UGX. For invoices where the amount is fractional after prorations, coupons, or taxes, Stripe automatically rounds that amount to the nearest number evenly divisible by 100. We credit or debit any difference from rounding to the customer balance.",
+      "note": "Contradiction on the live page: UGX is listed under \"Zero-decimal currencies\" (and in the embedded zero_decimal array), yet the Special cases row says it must be sent as a two-decimal value ending in 00 (5 UGX -> 500). The special-case text is the more specific instruction; confirm against the live API before relying on either.",
+      "unverified": true
+    },
+    "BHD": {
+      "apiExponent": 3,
+      "rule": "Three-decimal; last digit of amount must be 0 (amount % 10 == 0) for Payment Intents, Refunds, Disputes.",
+      "quote": "The API supports three-decimal currencies for the standard payment flows, including Payment Intents, Refunds, and Disputes. However, to ensure compatibility with Stripe’s payments partners, these API calls require the least-significant (last) digit to be 0. Your integration must round amounts to the nearest ten. For example, 5.124 KWD must be rounded to 5120 or 5130. Three-decimal currencies: BHD JOD KWD OMR TND",
+      "quoteSource": "https://web.archive.org/web/20240620024311/https://docs.stripe.com/currencies (section \"Three-decimal currencies\")",
+      "note": "The live page (fetched 2026-11-07) no longer has a \"Three-decimal currencies\" section; its meta description still says \"including zero-decimal and three-decimal currency support\", and the embedded presentment data lists BHD/JOD/KWD/OMR/TND only for UAE (AE) accounts. Rule quoted from the June 2024 archived version.",
+      "unverified": true
+    },
+    "JOD": {
+      "apiExponent": 3,
+      "rule": "Three-decimal; last digit of amount must be 0 (amount % 10 == 0) for Payment Intents, Refunds, Disputes.",
+      "quote": "The API supports three-decimal currencies for the standard payment flows, including Payment Intents, Refunds, and Disputes. However, to ensure compatibility with Stripe’s payments partners, these API calls require the least-significant (last) digit to be 0. Your integration must round amounts to the nearest ten. For example, 5.124 KWD must be rounded to 5120 or 5130. Three-decimal currencies: BHD JOD KWD OMR TND",
+      "quoteSource": "https://web.archive.org/web/20240620024311/https://docs.stripe.com/currencies (section \"Three-decimal currencies\")",
+      "note": "The live page (fetched 2026-11-07) no longer has a \"Three-decimal currencies\" section; its meta description still says \"including zero-decimal and three-decimal currency support\", and the embedded presentment data lists BHD/JOD/KWD/OMR/TND only for UAE (AE) accounts. Rule quoted from the June 2024 archived version.",
+      "unverified": true
+    },
+    "KWD": {
+      "apiExponent": 3,
+      "rule": "Three-decimal; last digit of amount must be 0 (amount % 10 == 0) for Payment Intents, Refunds, Disputes.",
+      "quote": "The API supports three-decimal currencies for the standard payment flows, including Payment Intents, Refunds, and Disputes. However, to ensure compatibility with Stripe’s payments partners, these API calls require the least-significant (last) digit to be 0. Your integration must round amounts to the nearest ten. For example, 5.124 KWD must be rounded to 5120 or 5130. Three-decimal currencies: BHD JOD KWD OMR TND",
+      "quoteSource": "https://web.archive.org/web/20240620024311/https://docs.stripe.com/currencies (section \"Three-decimal currencies\")",
+      "note": "The live page (fetched 2026-11-07) no longer has a \"Three-decimal currencies\" section; its meta description still says \"including zero-decimal and three-decimal currency support\", and the embedded presentment data lists BHD/JOD/KWD/OMR/TND only for UAE (AE) accounts. Rule quoted from the June 2024 archived version.",
+      "unverified": true
+    },
+    "OMR": {
+      "apiExponent": 3,
+      "rule": "Three-decimal; last digit of amount must be 0 (amount % 10 == 0) for Payment Intents, Refunds, Disputes.",
+      "quote": "The API supports three-decimal currencies for the standard payment flows, including Payment Intents, Refunds, and Disputes. However, to ensure compatibility with Stripe’s payments partners, these API calls require the least-significant (last) digit to be 0. Your integration must round amounts to the nearest ten. For example, 5.124 KWD must be rounded to 5120 or 5130. Three-decimal currencies: BHD JOD KWD OMR TND",
+      "quoteSource": "https://web.archive.org/web/20240620024311/https://docs.stripe.com/currencies (section \"Three-decimal currencies\")",
+      "note": "The live page (fetched 2026-11-07) no longer has a \"Three-decimal currencies\" section; its meta description still says \"including zero-decimal and three-decimal currency support\", and the embedded presentment data lists BHD/JOD/KWD/OMR/TND only for UAE (AE) accounts. Rule quoted from the June 2024 archived version.",
+      "unverified": true
+    },
+    "TND": {
+      "apiExponent": 3,
+      "rule": "Three-decimal; last digit of amount must be 0 (amount % 10 == 0) for Payment Intents, Refunds, Disputes.",
+      "quote": "The API supports three-decimal currencies for the standard payment flows, including Payment Intents, Refunds, and Disputes. However, to ensure compatibility with Stripe’s payments partners, these API calls require the least-significant (last) digit to be 0. Your integration must round amounts to the nearest ten. For example, 5.124 KWD must be rounded to 5120 or 5130. Three-decimal currencies: BHD JOD KWD OMR TND",
+      "quoteSource": "https://web.archive.org/web/20240620024311/https://docs.stripe.com/currencies (section \"Three-decimal currencies\")",
+      "note": "The live page (fetched 2026-11-07) no longer has a \"Three-decimal currencies\" section; its meta description still says \"including zero-decimal and three-decimal currency support\", and the embedded presentment data lists BHD/JOD/KWD/OMR/TND only for UAE (AE) accounts. Rule quoted from the June 2024 archived version.",
+      "unverified": true
+    }
+  },
+  "presentment": [
+    "AED",
+    "AFN",
+    "ALL",
+    "AMD",
+    "ANG",
+    "AOA",
+    "ARS",
+    "AUD",
+    "AWG",
+    "AZN",
+    "BAM",
+    "BBD",
+    "BDT",
+    "BHD",
+    "BIF",
+    "BMD",
+    "BND",
+    "BOB",
+    "BRL",
+    "BSD",
+    "BWP",
+    "BYN",
+    "BZD",
+    "CAD",
+    "CDF",
+    "CHF",
+    "CLP",
+    "CNY",
+    "COP",
+    "CRC",
+    "CVE",
+    "CZK",
+    "DJF",
+    "DKK",
+    "DOP",
+    "DZD",
+    "EGP",
+    "ETB",
+    "EUR",
+    "FJD",
+    "FKP",
+    "GBP",
+    "GEL",
+    "GIP",
+    "GMD",
+    "GNF",
+    "GTQ",
+    "GYD",
+    "HKD",
+    "HNL",
+    "HTG",
+    "HUF",
+    "IDR",
+    "ILS",
+    "INR",
+    "ISK",
+    "JMD",
+    "JOD",
+    "JPY",
+    "KES",
+    "KGS",
+    "KHR",
+    "KMF",
+    "KRW",
+    "KWD",
+    "KYD",
+    "KZT",
+    "LAK",
+    "LBP",
+    "LKR",
+    "LRD",
+    "LSL",
+    "MAD",
+    "MDL",
+    "MGA",
+    "MKD",
+    "MMK",
+    "MNT",
+    "MOP",
+    "MUR",
+    "MVR",
+    "MWK",
+    "MXN",
+    "MYR",
+    "MZN",
+    "NAD",
+    "NGN",
+    "NIO",
+    "NOK",
+    "NPR",
+    "NZD",
+    "OMR",
+    "PAB",
+    "PEN",
+    "PGK",
+    "PHP",
+    "PKR",
+    "PLN",
+    "PYG",
+    "QAR",
+    "RON",
+    "RSD",
+    "RUB",
+    "RWF",
+    "SAR",
+    "SBD",
+    "SCR",
+    "SEK",
+    "SGD",
+    "SHP",
+    "SLE",
+    "SOS",
+    "SRD",
+    "STD",
+    "SZL",
+    "THB",
+    "TJS",
+    "TND",
+    "TOP",
+    "TRY",
+    "TTD",
+    "TWD",
+    "TZS",
+    "UAH",
+    "UGX",
+    "USD",
+    "UYU",
+    "UZS",
+    "VND",
+    "VUV",
+    "WST",
+    "XAF",
+    "XCD",
+    "XCG",
+    "XOF",
+    "XPF",
+    "YER",
+    "ZAR",
+    "ZMW"
+  ],
+  "presentmentNotes": {
+    "count": 139,
+    "union": "Union over all 45 account countries in the page's embedded SupportedPresentmentCurrencies data. 134 codes for every country except AE, which additionally has BHD, JOD, KWD, OMR, TND.",
+    "noAmexSupport": [
+      "AFN",
+      "AOA",
+      "ARS",
+      "BOB",
+      "BRL",
+      "CLP",
+      "COP",
+      "CRC",
+      "CVE",
+      "DJF",
+      "FKP",
+      "GNF",
+      "GTQ",
+      "HNL",
+      "LAK",
+      "MUR",
+      "NIO",
+      "PAB",
+      "PEN",
+      "PYG",
+      "SHP",
+      "SRD",
+      "STD",
+      "SVC",
+      "UYU",
+      "XOF",
+      "XPF"
+    ],
+    "noAmexSupportCountries": [
+      "AE",
+      "BR",
+      "MY",
+      "TH"
+    ],
+    "nonIsoOrWithdrawn": {
+      "ANG": "ISO withdrew ANG 2025-03 (Curaçao and Sint Maarten moved to XCG); Stripe lists both ANG and XCG.",
+      "STD": "ISO withdrew STD 2017-12 (replaced by STN); Stripe still lists STD, not STN."
+    },
+    "casing": "Stripe requires lowercase codes in API requests."
+  }
+}

package/dist/adyen-fx.d.ts

@@ -0,0 +1,25 @@
+import { type Rate } from './rate.js';
+/** Options for adyenRate. */
+export interface AdyenRateOptions {
+    /**
+     * The account's IANA time zone ('Europe/Amsterdam'). When given, Creation Date is read in it,
+     * summer time included, and the TimeZone column is not used.
+     */
+    readonly timeZone?: string;
+}
+/** A settlement details report row, keyed by column name (as from a CSV parser with headers). */
+export type AdyenSettlementRow = Readonly<Record<string, string | undefined>>;
+/**
+ * The rate in a settlement details report row: "The exchange rate used for converting the gross
+ * amount into the net amount", Gross Currency → Net Currency (1 when they are the same). The
+ * decimal string is kept exactly. `asOf` comes from Creation Date, which Adyen gives in local time,
+ * with the zone in the TimeZone column. Pass `{ timeZone: 'Europe/Amsterdam' }` (the account's IANA
+ * zone) to read it correctly all year. Without it, an unambiguous abbreviation (CET, PST, ...) or
+ * offset (+01:00) is taken literally: Adyen's documentation doesn't say whether the column switches
+ * to CEST in summer, and if it doesn't, a literal CET is an hour off then. Any other label gives
+ * the local day, which can be a day off from UTC. `undefined` when the row has no rate. For
+ * externally settled payments Adyen lists its reference rate, not the acquirer's, so check those
+ * with impliedRate().
+ */
+export declare function adyenRate(row: AdyenSettlementRow, options?: AdyenRateOptions): Rate | undefined;
+//# sourceMappingURL=adyen-fx.d.ts.map

package/dist/adyen-fx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adyen-fx.d.ts","sourceRoot":"","sources":["../src/adyen-fx.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,IAAI,EAAiB,MAAM,WAAW,CAAC;AAkInE,6BAA6B;AAC7B,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,iGAAiG;AACjG,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAE9E;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,CAmB/F"}

package/dist/adyen-fx.js

@@ -0,0 +1,140 @@
+// Adyen exchange rates as exact Rates, from settlement details report rows.
+import { exchangeRate } from './rate.js';
+// UTC offsets, in minutes, of the zone abbreviations that name one offset. Ambiguous ones are left
+// out on purpose: IST is India, Ireland or Israel; CST is US Central or China; BST is British or
+// Bangladesh.
+const ZONE_OFFSET_MINUTES = {
+    UTC: 0,
+    GMT: 0,
+    WET: 0,
+    WEST: 60,
+    CET: 60,
+    CEST: 120,
+    EET: 120,
+    EEST: 180,
+    MSK: 180,
+    SGT: 480,
+    HKT: 480,
+    JST: 540,
+    KST: 540,
+    AEST: 600,
+    AEDT: 660,
+    NZST: 720,
+    NZDT: 780,
+    EST: -300,
+    EDT: -240,
+    MST: -420,
+    MDT: -360,
+    PST: -480,
+    PDT: -420,
+};
+const LOCAL_TIME = /^(\d{4}-\d\d-\d\d)[ T](\d\d:\d\d(?::\d\d(?:\.\d+)?)?)$/;
+const NUMERIC_OFFSET = /^(?:UTC|GMT)?\s*([+-])(\d{1,2})(?::?(\d\d))?$/;
+// Real UTC offsets run from -12:00 to +14:00.
+const MAX_OFFSET_MINUTES = 14 * 60;
+/** The zone's offset in minutes, or undefined when it can't be read unambiguously. */
+function offsetMinutes(zone) {
+    const named = ZONE_OFFSET_MINUTES[zone.toUpperCase()];
+    if (named !== undefined) {
+        return named;
+    }
+    const numeric = NUMERIC_OFFSET.exec(zone);
+    if (numeric === null) {
+        return undefined;
+    }
+    const hours = Number(numeric[2]);
+    const minutes = Number(numeric[3] ?? 0);
+    const total = hours * 60 + minutes;
+    if (minutes >= 60 || total > MAX_OFFSET_MINUTES) {
+        return undefined;
+    }
+    return numeric[1] === '-' ? -total : total;
+}
+// Building an Intl.DateTimeFormat is far slower than using one, and a report has thousands of rows
+// in one zone, so keep one formatter per zone. The bound stops a stream of distinct zone names
+// (case variants are accepted by Intl) from growing the cache without limit.
+const MAX_CACHED_FORMATTERS = 32;
+const formatters = new Map();
+/** The cached wall-clock formatter for an IANA time zone. */
+function wallClockFormatter(timeZone) {
+    let formatter = formatters.get(timeZone);
+    if (formatter !== undefined) {
+        return formatter;
+    }
+    formatter = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: 'numeric',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: 'numeric',
+        second: 'numeric',
+    });
+    if (formatters.size >= MAX_CACHED_FORMATTERS) {
+        formatters.clear();
+    }
+    formatters.set(timeZone, formatter);
+    return formatter;
+}
+/** The offset of an IANA time zone at a UTC instant, in minutes. */
+function ianaOffsetMinutes(timeZone, utcMs) {
+    const parts = wallClockFormatter(timeZone).formatToParts(new Date(utcMs));
+    const field = (type) => Number(parts.find((part) => part.type === type).value);
+    const wallClockAsUtc = Date.UTC(field('year'), field('month') - 1, field('day'), field('hour'), field('minute'), field('second'));
+    return Math.round((wallClockAsUtc - Math.floor(utcMs / 1000) * 1000) / 60_000);
+}
+/** The UTC instant of a wall-clock time in an IANA zone, summer time included. */
+function ianaToUtc(localAsUtcMs, timeZone) {
+    // The offset at the guess can differ from the offset at the answer across a clock change, so
+    // look it up again at the first answer.
+    const firstGuess = localAsUtcMs - ianaOffsetMinutes(timeZone, localAsUtcMs) * 60_000;
+    return localAsUtcMs - ianaOffsetMinutes(timeZone, firstGuess) * 60_000;
+}
+/** Creation Date as a UTC instant when its zone is known; otherwise its local day. */
+function creationAsOf(created, label, timeZone) {
+    const local = LOCAL_TIME.exec(created.trim());
+    if (local === null) {
+        return /^\d{4}-\d\d-\d\d/.test(created) ? created.slice(0, 10) : undefined;
+    }
+    const localAsUtcMs = Date.parse(`${local[1]}T${local[2]}Z`);
+    if (timeZone !== undefined) {
+        return new Date(ianaToUtc(localAsUtcMs, timeZone)).toISOString();
+    }
+    const offset = label === undefined ? undefined : offsetMinutes(label.trim());
+    if (offset === undefined) {
+        return local[1];
+    }
+    return new Date(localAsUtcMs - offset * 60_000).toISOString();
+}
+/**
+ * The rate in a settlement details report row: "The exchange rate used for converting the gross
+ * amount into the net amount", Gross Currency → Net Currency (1 when they are the same). The
+ * decimal string is kept exactly. `asOf` comes from Creation Date, which Adyen gives in local time,
+ * with the zone in the TimeZone column. Pass `{ timeZone: 'Europe/Amsterdam' }` (the account's IANA
+ * zone) to read it correctly all year. Without it, an unambiguous abbreviation (CET, PST, ...) or
+ * offset (+01:00) is taken literally: Adyen's documentation doesn't say whether the column switches
+ * to CEST in summer, and if it doesn't, a literal CET is an hour off then. Any other label gives
+ * the local day, which can be a day off from UTC. `undefined` when the row has no rate. For
+ * externally settled payments Adyen lists its reference rate, not the acquirer's, so check those
+ * with impliedRate().
+ */
+export function adyenRate(row, options) {
+    const gross = row['Gross Currency'];
+    const net = row['Net Currency'];
+    const rate = row['Exchange Rate']?.trim();
+    if (gross === undefined || gross === '' || net === undefined || net === '') {
+        return undefined;
+    }
+    if (rate === undefined || rate === '') {
+        return undefined;
+    }
+    const created = row['Creation Date'];
+    let info = { source: 'adyen' };
+    const asOf = created === undefined ? undefined : creationAsOf(created, row['TimeZone'], options?.timeZone);
+    if (asOf !== undefined) {
+        info = { source: 'adyen', asOf };
+    }
+    return exchangeRate(gross, net, rate, info);
+}
+//# sourceMappingURL=adyen-fx.js.map

package/dist/adyen-fx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adyen-fx.js","sourceRoot":"","sources":["../src/adyen-fx.ts"],"names":[],"mappings":"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"}