@amboras-dev/money 0.0.0-stage → 0.2.0

package/dist/wire-CaUN9Vf_.d.ts

@@ -0,0 +1,309 @@
+import { b as FractionDigits, g as CurrencyCode, i as Money, o as StoredAmount, t as FractionalMoney, z as RoundingMode } from "./money-B-3aFjNJ.js";
+//#region src/wire/anet.d.ts
+/**
+ * The first `"<field>": <decimal>` (quoted or not) in a raw JSON body, verbatim: `JSON.parse`
+ * would turn the gateway's `43.00` into `43`. The value is the whole JSON token, held to
+ * `parseDecimal`'s `'plain'` grammar (`1e3` or `"43.10abc"` is not a decimal literal).
+ * Undefined when absent; there is no lossy fallback.
+ */
+declare function jsonDecimalLiteral(rawBody: string, field: string): string | undefined;
+/**
+ * What an unsettled Authorize.Net transaction can still be reversed for: the settle amount when
+ * present and above zero (exact), else `authAmount ?? settleAmount` (settle is `'0.00'`, not
+ * absent, for voided or unsettled transactions). Undefined when both are absent.
+ */
+interface AuthorizeNetAmounts {
+  settleAmount?: string | null;
+  authAmount?: string | null;
+}
+declare function authorizeNetReversibleAmount(details: AuthorizeNetAmounts): string | undefined;
+//#endregion
+//#region src/wire/descriptors.d.ts
+type PspId = 'stripe' | 'adyen' | 'razorpay' | 'paystack' | 'momo' | 'vnpay' | 'paypal' | 'mollie' | 'airwallex' | 'iyzico' | 'authorize-net' | 'payoo';
+/** ISO minor units, marker-gated decode: a payment created before the cutover holds storage units at the PSP. */
+type GatedPsp = 'stripe' | 'adyen' | 'razorpay' | 'paystack' | 'momo';
+/** Gated PSPs whose encode is gated too; MoMo and Paystack always encode ISO minor units. */
+type EncodeGatedPsp = 'stripe' | 'adyen' | 'razorpay';
+type IsoMinorPsp = GatedPsp | 'vnpay';
+type MajorStringPsp = 'paypal' | 'mollie' | 'iyzico' | 'authorize-net';
+type MajorNumberPsp = 'airwallex' | 'payoo';
+/** What a PSP receives: major-unit text for PayPal, Mollie, iyzico and Authorize.Net, a number for the rest. */
+type WireAmount<P extends PspId> = P extends MajorStringPsp ? string : number;
+/** Every PSP id, in a stable order. */
+declare const PSP_IDS: readonly PspId[];
+//#endregion
+//#region src/wire/marker.d.ts
+declare const WIRE_SCALE_KEY = "amboras_wire_scale";
+declare const WIRE_SCALE_ISO_MINOR_V2 = "iso-minor-v2";
+declare const WIRE_SCALE_MARKER: Readonly<{
+  amboras_wire_scale: 'iso-minor-v2';
+}>;
+/** Which convention a payment was created under. Use the two singletons; build one with `conventionOf`. */
+type Convention = {
+  readonly kind: 'iso-minor-v2';
+} | {
+  readonly kind: 'pre-cutover';
+};
+declare const ISO_MINOR_V2: Convention;
+declare const PRE_CUTOVER: Convention;
+/**
+ * `ISO_MINOR_V2` iff ANY record is a non-null object whose `amboras_wire_scale` is strictly
+ * `'iso-minor-v2'` (a Stripe charge OR its PaymentIntent); else `PRE_CUTOVER`. Reads already
+ * fetched records only: it never queries (FORCE RLS would hide the row and the marker with it).
+ */
+declare function conventionOf(...records: unknown[]): Convention;
+//#endregion
+//#region src/wire/breakdown.d.ts
+/**
+ * `total` and its `parts` (same currency, non-negative, adding up to `total`) as integer wire
+ * amounts whose sum is exactly `encodeWire(psp, total)`: the wire total split by largest
+ * remainder over the stored parts. Throws `currency_mismatch`, `amount_invalid` (parts that do not
+ * add up, or a negative part) or whatever `encodeWire` refuses.
+ */
+declare function wireBreakdown(psp: IsoMinorPsp, total: Money, parts: Readonly<Record<string, Money>>, convention: Convention): {
+  total: number;
+  parts: Record<string, number>;
+};
+//#endregion
+//#region src/wire/codec.d.ts
+/** Whether `psp` takes `currency` (any case, historic codes included). Never throws for a bad code. */
+declare function pspSupportsCurrency(psp: PspId, currency: string): boolean;
+/**
+ * Every currency `psp` takes. Provider-only codes a PSP table lists (Adyen offshore CNH) are left
+ * out: they are not ISO 4217 currencies, no store sells in them and no Money can carry them.
+ */
+declare function pspCurrencies(psp: PspId): ReadonlySet<CurrencyCode>;
+/**
+ * `currency` as a CurrencyCode `psp` takes. Empty throws `currency_missing` (`[<Tag>] Cannot
+ * scale an amount without a currency code; ...`); anything the PSP does not take throws
+ * `wire_unsupported` with the provider's own message.
+ */
+declare function assertPspCurrency(psp: PspId, currency: unknown): CurrencyCode;
+/** `'VND'` for the single-currency providers (MoMo, Payoo, VNPay), else null. */
+declare function pspDefaultCurrency(psp: PspId): CurrencyCode | null;
+/**
+ * Stored units per wire unit for an ISO-minor PSP: the PSP's override (Stripe ISK/UGX, Adyen
+ * ISK/CLP, Razorpay MGA, Paystack XOF, VNPay VND give 1; Adyen IDR/CVE give 100), else
+ * `storageScale / 10^storageDigits` (100 for a zero-decimal currency, else 1).
+ */
+declare function wireFactor(psp: IsoMinorPsp, currency: string): 1 | 100;
+/**
+ * Fraction digits of `psp`'s wire amount: its digit table, else (ISO-minor PSPs) the digits
+ * its factor implies, else (iyzico, Authorize.Net, Payoo) the display digits. Null when the
+ * PSP does not take the currency.
+ */
+declare function pspWireDigits(psp: PspId, currency: string): FractionDigits | null;
+/** The PSP's minimum charge in `currency` (Paystack USD 2.00), or null when it has none. */
+declare function pspMinimumAmount(psp: PspId, currency: string): Money | null;
+interface EncodeWireOptions {
+  /** Names the amount in refusals: `[<Tag>] Invalid <label>: <amount>`. Default `'amount'`; refunds pass `'refund amount'`. */
+  label?: string;
+  /** Allow a zero amount (verification, comparisons). Negative amounts are always refused. */
+  allowZero?: boolean;
+}
+/**
+ * A stored amount as `psp` receives it. `m` is a Money or a FractionalMoney (Medusa's unrounded
+ * session totals, 107.8175). In order: the currency must pass the PSP's Medusa amount facade
+ * (`wire_unsupported` with the facade's message: Razorpay only its exponent table, Paystack no
+ * zero-decimal code but XOF, MoMo, Payoo and VNPay only VND; every other PSP scales any currency,
+ * so call `assertPspCurrency` for eligibility); the amount must be positive (`wire_refused`
+ * `[<Tag>] Invalid <label>: <amount>`, zero allowed with `allowZero`); Stripe and Adyen round a
+ * fractional amount half-up to a whole storage unit first; Stripe, Adyen and Razorpay on a
+ * pre-cutover payment send the stored integer as is (Razorpay refuses unless its factor is 1, and
+ * refuses a fractional amount, which has no stored integer; MoMo and Paystack encode ignore the
+ * convention, as today); the whole-unit rules refuse fractions of a dong (MoMo, Payoo, VNPay) or a
+ * franc (Paystack XOF), naming the amount as held; then, rounding once and exactly, ISO minor
+ * `half-up(S / wireFactor)` (Razorpay three-decimal floored to steps of 10), or major units at the
+ * PSP's wire digits, half-up, as fixed-point text (a number for Airwallex and Payoo). A positive
+ * amount whose wire rounds to zero is refused (`wire_refused`), with `allowZero` too.
+ * This is package policy, safer than Medusa today: Medusa puts 0 on the wire at initiate for
+ * Stripe and Adyen, and for Razorpay, PayPal and Airwallex everywhere; it refuses at refund and
+ * capture for Stripe and Adyen, and in Mollie, iyzico and Authorize.Net; Razorpay and Paystack
+ * read a zero refund as a full one. Otherwise byte-identical to Medusa's codecs for every Money.
+ */
+declare function encodeWire<P extends EncodeGatedPsp>(psp: P, m: Money | FractionalMoney, options: EncodeWireOptions & {
+  convention: Convention;
+}): WireAmount<P>;
+declare function encodeWire<P extends Exclude<PspId, EncodeGatedPsp>>(psp: P, m: Money | FractionalMoney, options?: EncodeWireOptions): WireAmount<P>;
+/**
+ * A PSP wire amount as Money: ISO minor `half-up(w x wireFactor)` (pre-cutover: `half-up(w)`, the
+ * PSP already held storage units), major `half-up(w x storageScale)`. `wire` is a finite number
+ * or strict decimal text (`/^-?\d+(\.\d+)?$/`: no `''`, exponent or hex), else `amount_invalid`.
+ * Signed, except VNPay, where anything but a positive whole number is no amount (`amount_invalid`).
+ * The currency is required (`currency_missing`), must be known (`currency_invalid`), must not be
+ * provider-only (Adyen CNH: `wire_unsupported`), and must pass the PSP's Medusa inbound gate
+ * (`wire_unsupported` with its message: Razorpay only its exponent table, Paystack no
+ * zero-decimal code but XOF, MoMo, Payoo and VNPay only VND). Other PSPs read any currency (a PSP
+ * may report a settlement currency).
+ */
+declare function decodeWire<P extends GatedPsp>(psp: P, wire: unknown, currency: string, convention: Convention): Money;
+declare function decodeWire<P extends Exclude<PspId, GatedPsp>>(psp: P, wire: unknown, currency: string): Money;
+interface TryDecodeWireOptions {
+  /** Required for gated PSPs (Stripe, Adyen, Razorpay, Paystack, MoMo): without it the result is undefined. */
+  convention?: Convention;
+  /** Accept a negative wire amount (balance transactions, reversals). Default false; never for VNPay. */
+  allowNegative?: boolean;
+}
+/**
+ * `decodeWire` that never throws: undefined wherever it would throw (null, undefined, `''`,
+ * whitespace, unparseable or unsafe input, a missing, unknown or provider-only currency, one the
+ * PSP's inbound gate refuses, VNPay's "no amount", an unknown PSP, a gated PSP without
+ * `convention`: no hidden default) and for a negative amount unless `allowNegative`.
+ */
+declare function tryDecodeWire(psp: PspId, wire: unknown, currency: unknown, options?: TryDecodeWireOptions): Money | undefined;
+//#endregion
+//#region src/wire/compare.d.ts
+interface SameWireAmountOptions {
+  /** Required for gated PSPs (Stripe, Adyen, Razorpay, Paystack, MoMo); without it the answer is false. */
+  convention?: Convention;
+  /**
+   * Also accept the ISO-digit spelling held by a session created before the PSP digit tables
+   * (PayPal, Mollie, Airwallex HUF/TWD...): the expected amount in major units at its display
+   * digits, half-up (HUF 44.50 went as `'45'`). Major-unit PSPs only.
+   */
+  acceptLegacyIsoDigits?: boolean;
+  /**
+   * The PSP only ever reports decimal text (Mollie, PayPal): a reported (or `requested`) value
+   * that is not a string is not its amount, whatever number it holds.
+   */
+  textOnly?: boolean;
+  /** When given, it must be the same currency as `expected` (any case). */
+  reportedCurrency?: unknown;
+  /** Paystack fee pass-through: the amount the buyer was asked for. */
+  requested?: unknown;
+  /**
+   * `'exact'` (default), or `'requested-exact-collected-covers'`: `requested` is exactly the
+   * expected amount and the collected `reported` covers it.
+   */
+  policy?: 'exact' | 'requested-exact-collected-covers';
+}
+/**
+ * Whether a PSP-reported amount is `expected`, a Money or a FractionalMoney (Medusa's unrounded
+ * session total). The expected wire is `encodeWire(psp, expected, { convention, allowZero: true })`
+ * (a refusal means false); the reported one must decode exactly (strict like `tryDecodeWire`:
+ * never `''` or an exponent, no negatives, and never a fraction of a storage unit) to the same
+ * stored amount, so `'44.00'` matches a sent `'44'` and Airwallex `43.004` does not match `43`.
+ * Never throws.
+ */
+declare function sameWireAmount(psp: PspId, reported: unknown, expected: Money | FractionalMoney, options?: SameWireAmountOptions): boolean;
+/**
+ * One unit of the PSP's last wire digit, as Money: for ISO-minor PSPs `decodeWire(psp, 1)` (the
+ * factor on an iso-minor-v2 payment, 1 storage unit on a pre-cutover one; gated PSPs need the
+ * convention), for major PSPs `10^-wireDigits` major. The tolerance for `excessOver`.
+ */
+declare function oneWireUnit(psp: PspId, currency: string, convention?: Convention): Money;
+/** The wire amount as it goes into Redis skip keys and idempotency keys: `String(wire)`, byte for byte. */
+declare function wireKeyPart(wire: number | string): string;
+//#endregion
+//#region src/data/destinations.d.ts
+type DestinationId = 'meta' | 'ga4' | 'google-ads' | 'tiktok' | 'snapchat' | 'pinterest' | 'klaviyo' | 'omnisend' | 'omnisend-viewed-product' | 'mailchimp' | 'goaffpro' | 'profitmetrics' | 'pixi' | 'flow' | 'sendcloud' | 'shipstation' | 'shiprocket' | 'shipbob' | 'printful' | 'ahamove' | 'amazon-mcf' | 'skydropx' | 'royal-mail' | 'sevdesk' | 'shopify-ajax';
+//#endregion
+//#region src/wire/destinations.d.ts
+interface DestinationValue {
+  readonly value: number | string;
+  readonly currency: string;
+}
+/**
+ * `m` as `dest` wants it: major units at the display digits (half-up) as a number or text per
+ * destination (`as` overrides), or integer "cents" for Shopify AJAX and Omnisend `viewed product`;
+ * the currency upper- or lower-case per destination. Undefined when the destination must not get
+ * this amount (Meta: not positive; GA4, Google Ads, TikTok, Snapchat, Pinterest and marketing:
+ * negative). Throws `wire_unsupported` for a currency the destination's unit is not defined for.
+ */
+declare function destinationAmount(dest: DestinationId, m: Money, options?: {
+  as?: 'number' | 'string';
+}): DestinationValue | undefined;
+/** A shopping-feed price: `'12.345 KWD'`, `'1200 JPY'`, `'19.99 USD'` (display digits, half-up). */
+declare function feedPrice(m: Money): string;
+/** Google micros (major x 10^6) as integer text, exactly: USD 1999 gives `'19990000'`. */
+declare function googleMicros(m: Money): string;
+interface EventMoney {
+  readonly value: number;
+  readonly currency: string;
+}
+/** First-party analytics money: the stored integer and the lower-case code (the ClickHouse `Int64` contract). */
+declare function eventMoney(m: Money): EventMoney;
+//#endregion
+//#region src/wire/presentment.d.ts
+interface PspPresentment {
+  /** Every currency some account of the PSP can present: the union over account countries. */
+  readonly currencies: ReadonlySet<CurrencyCode>;
+  /** Currencies only accounts registered in these countries can present (Stripe KWD: AE; PayPal BRL: BR). */
+  readonly currencyRequiresAccountCountry: ReadonlyMap<CurrencyCode, ReadonlySet<string>>;
+  /** Account countries limited to these currencies (Airwallex cards on a US or MX account). */
+  readonly accountCountryAllowsOnly: ReadonlyMap<string, ReadonlySet<CurrencyCode>>;
+}
+/**
+ * The PSP's presentment rules, as data: the union of currencies some account can charge, the
+ * currencies that need an account in particular countries, and the account countries limited to
+ * a list. For capability declarations that hold the rules themselves; `pspPresentmentCurrencies`
+ * applies them to one account. Fresh collections on every call. An unknown PSP throws
+ * `wire_unsupported`.
+ */
+declare function pspPresentment(psp: PspId): PspPresentment;
+/**
+ * The currencies `psp` lets an account present (charge buyers in). Without `accountCountry`, the
+ * union over every account country; with it (ISO 3166 alpha-2, any case), only what an account
+ * registered there can charge: Stripe's three-decimal five need a UAE account, PayPal's BRL, CNY
+ * and MYR an in-country one, Airwallex cards on a US account take its documented 76 and on an MX
+ * account MXN only. Not `pspCurrencies`, which is what the codec scales and the facade lets
+ * through (Stripe's adds every two-decimal ISO code it accepts on the wire).
+ */
+declare function pspPresentmentCurrencies(psp: PspId, options?: {
+  accountCountry?: string;
+}): ReadonlySet<CurrencyCode>;
+//#endregion
+//#region src/wire/provider-amount.d.ts
+interface ProviderAmountOptions {
+  /** Accept a negative amount (refunds, credits). Default false. */
+  allowNegative?: boolean;
+  /** Default `'.'`; `'auto'` decides from the text (see the core separator engine). */
+  decimalSeparator?: '.' | ',' | 'auto';
+  /** Read the first number and ignore the rest (`'22.67 + KDV'`). Default false. */
+  allowTrailingText?: boolean;
+  /** Rounding to the currency's storage digits (and the 'auto' whole-unit rounding). Default `'half-up'`. */
+  rounding?: RoundingMode;
+}
+/**
+ * A provider's major-unit amount (finite number, or text read by the separator engine, which
+ * strips the currency's symbol and code) as Money, rounded once to the storage digits. Null on
+ * anything invalid (empty, unparseable, non-finite, negative without `allowNegative`, too large,
+ * unknown currency), never 0.
+ */
+declare function parseProviderAmount(value: unknown, currency: string, options?: ProviderAmountOptions): Money | null;
+//#endregion
+//#region src/wire/providers.d.ts
+/** RBI e-mandate cap Razorpay token registrations carry as `max_amount`: INR 15,000 (1,500,000 paise = stored). */
+declare const RAZORPAY_AFA_FREE_CAP: Money;
+/**
+ * The symbolic charge a saved-card setup makes: Paystack one major unit, Razorpay one INR (any
+ * other currency is `wire_unsupported`), Mollie one smallest wire unit (`'0.01'`, `'1'` for ISK
+ * and JPY), Adyen zero. Vault charges are always new, so the iso-minor-v2 convention applies.
+ */
+declare function verificationCharge(psp: 'paystack' | 'razorpay' | 'mollie' | 'adyen', currency: string): {
+  wire: number | string;
+  money: Money;
+};
+/**
+ * iyzico's price spelling, on the text (no float): canonical decimal (no trailing fraction zeros),
+ * then `'.0'` when there is no `.` (`'10.50'` gives `'10.5'`, `'10.00'` gives `'10.0'`). Text that
+ * is not a plain decimal throws `parse`.
+ */
+declare function iyzicoPrice(wire: string): string;
+//#endregion
+//#region src/wire/slot.d.ts
+interface SlotMoney {
+  readonly amount: StoredAmount;
+  /** Lower-case, as Medusa spells it. */
+  readonly currency_code: string;
+}
+/** `m` for a slot context's `money` key. */
+declare function slotMoney(m: Money): SlotMoney;
+/**
+ * The money a slot context carries: `context.money` when it is valid, else the legacy
+ * `total ?? price` with the first known of `currency_code`, `currency`, read leniently (numbers, numeric text,
+ * Medusa BigNumber shapes). Undefined when the amount or the currency is missing or unreadable.
+ */
+declare function readSlotMoney(context: unknown): SlotMoney | undefined;
+//#endregion
+export { jsonDecimalLiteral as $, pspMinimumAmount as A, WIRE_SCALE_KEY as B, EncodeWireOptions as C, encodeWire as D, decodeWire as E, wireBreakdown as F, IsoMinorPsp as G, conventionOf as H, Convention as I, PSP_IDS as J, MajorNumberPsp as K, ISO_MINOR_V2 as L, pspWireDigits as M, tryDecodeWire as N, pspCurrencies as O, wireFactor as P, authorizeNetReversibleAmount as Q, PRE_CUTOVER as R, wireKeyPart as S, assertPspCurrency as T, EncodeGatedPsp as U, WIRE_SCALE_MARKER as V, GatedPsp as W, WireAmount as X, PspId as Y, AuthorizeNetAmounts as Z, googleMicros as _, iyzicoPrice as a, oneWireUnit as b, parseProviderAmount as c, pspPresentmentCurrencies as d, DestinationValue as f, feedPrice as g, eventMoney as h, RAZORPAY_AFA_FREE_CAP as i, pspSupportsCurrency as j, pspDefaultCurrency as k, PspPresentment as l, destinationAmount as m, readSlotMoney as n, verificationCharge as o, EventMoney as p, MajorStringPsp as q, slotMoney as r, ProviderAmountOptions as s, SlotMoney as t, pspPresentment as u, DestinationId as v, TryDecodeWireOptions as w, sameWireAmount as x, SameWireAmountOptions as y, WIRE_SCALE_ISO_MINOR_V2 as z };