@classytic/primitives 0.18.0 → 0.19.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +36 -0
- package/dist/monetization.d.mts +195 -0
- package/dist/monetization.mjs +79 -0
- package/dist/proration.d.mts +76 -0
- package/dist/proration.mjs +120 -0
- package/package.json +9 -1
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,42 @@
|
|
|
3
3
|
Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
4
4
|
adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
5
5
|
|
|
6
|
+
## [0.19.0] - 2026-08-01
|
|
7
|
+
|
|
8
|
+
### Added — `./monetization`: canonical pricing classification contract
|
|
9
|
+
|
|
10
|
+
- **`@classytic/primitives/monetization`** — the single home for how a product
|
|
11
|
+
is sold and priced, so the classification survives end-to-end across catalog,
|
|
12
|
+
revenue, order, and entitlement kernels without each maintaining its own enum.
|
|
13
|
+
- **`Monetization`** discriminated union — `FreeMonetization | OneTimeMonetization |
|
|
14
|
+
SubscriptionMonetization | BundleMonetization | UsageMonetization`, each
|
|
15
|
+
carrying its own nested pricing shape.
|
|
16
|
+
- **`MONETIZATION_KINDS`** + **`MonetizationKind`** + **`isMonetizationKind`** —
|
|
17
|
+
exhaustive kind list with runtime guard.
|
|
18
|
+
- Type-guard predicates: **`isFreeMonetization`**, **`isOneTimeMonetization`**,
|
|
19
|
+
**`isSubscriptionMonetization`**, **`isBundleMonetization`**,
|
|
20
|
+
**`isUsageMonetization`**.
|
|
21
|
+
- Supporting types: `PriceTier`, `OneTimePricing`, `SubscriptionPlan`,
|
|
22
|
+
`UsageTier`, `UsageRating`, `DurationUnit`, `MoneyByCurrency`.
|
|
23
|
+
|
|
24
|
+
### Added — `./proration`: pure proration arithmetic
|
|
25
|
+
|
|
26
|
+
- **`@classytic/primitives/proration`** — timezone-agnostic, policy-free
|
|
27
|
+
proration math. Holds no commercial policy (no upgrade/downgrade semantics,
|
|
28
|
+
no discount or tax logic) — those live in the contract kernel.
|
|
29
|
+
- **`periodProgress(input)`** — fraction of a billing period consumed given
|
|
30
|
+
start, end, and current instants as `Date`. Returns `PeriodFraction`.
|
|
31
|
+
- **`splitByPeriodFraction(amount, fraction, granularity?)`** — split a `Money`
|
|
32
|
+
amount into consumed/remaining parts; `granularity: 'whole_day'` (default) or
|
|
33
|
+
`'exact'`.
|
|
34
|
+
- **`allocateMoneyByFraction(amount, fraction)`** — proportional allocation
|
|
35
|
+
using the largest-remainder allocator so `consumed + remaining === amount`
|
|
36
|
+
exactly (no penny drift).
|
|
37
|
+
- **`ProrationError`** + **`ProrationErrorCode`** (`INVALID_PERIOD` |
|
|
38
|
+
`INVALID_FRACTION`) — typed errors for out-of-range inputs.
|
|
39
|
+
- Supporting types: `PeriodFraction`, `PeriodProgressInput`,
|
|
40
|
+
`ProrationGranularity`.
|
|
41
|
+
|
|
6
42
|
## [0.18.0] - 2026-07-29
|
|
7
43
|
|
|
8
44
|
### Added — `./subject`: `SubjectRef` polymorphic identity pointer
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
import { Money } from "./money.mjs";
|
|
2
|
+
|
|
3
|
+
//#region src/money/monetization.d.ts
|
|
4
|
+
/**
|
|
5
|
+
* A map of currency code → {@link Money} for explicit per-currency pricing.
|
|
6
|
+
* Explicit entries always win over a currency-conversion fallback.
|
|
7
|
+
*
|
|
8
|
+
* Canonical home (was hand-declared in `@classytic/catalog`; re-exported there
|
|
9
|
+
* for back-compat). Belongs with money because it is a money-shaped value.
|
|
10
|
+
*/
|
|
11
|
+
type MoneyByCurrency = Record<string, Money>;
|
|
12
|
+
/**
|
|
13
|
+
* The canonical monetization kinds. Order is stable; append only.
|
|
14
|
+
*
|
|
15
|
+
* - `free` — no charge.
|
|
16
|
+
* - `one_time` — charged once (catalog `one_time`; revenue `purchase`).
|
|
17
|
+
* - `subscription` — recurring plan / membership.
|
|
18
|
+
* - `bundle` — a composite priced from its members.
|
|
19
|
+
* - `usage` — metered / per-seat / consumption (billed per unit or in
|
|
20
|
+
* arrears). The extension point for rating models.
|
|
21
|
+
*/
|
|
22
|
+
declare const MONETIZATION_KINDS: readonly ["free", "one_time", "subscription", "bundle", "usage"];
|
|
23
|
+
type MonetizationKind = (typeof MONETIZATION_KINDS)[number];
|
|
24
|
+
/** True when `value` is one of the canonical kinds. */
|
|
25
|
+
declare function isMonetizationKind(value: unknown): value is MonetizationKind;
|
|
26
|
+
/** A quantity-based price break. `price` (fixed override) XOR `discountPercent`. */
|
|
27
|
+
interface PriceTier {
|
|
28
|
+
/** Minimum quantity to qualify. */
|
|
29
|
+
readonly minQuantity: number;
|
|
30
|
+
/** Fixed override price for this tier. */
|
|
31
|
+
readonly price?: Money;
|
|
32
|
+
/** OR a percentage discount (0–100). Mutually exclusive with `price`. */
|
|
33
|
+
readonly discountPercent?: number;
|
|
34
|
+
}
|
|
35
|
+
interface OneTimePricing {
|
|
36
|
+
/** Required base (list) price. */
|
|
37
|
+
readonly basePrice: Money;
|
|
38
|
+
/** Default currency (redundant with `basePrice.currency`, indexed for queries). */
|
|
39
|
+
readonly currency: string;
|
|
40
|
+
/** Optional strikethrough / MSRP price. */
|
|
41
|
+
readonly compareAtPrice?: Money;
|
|
42
|
+
/** Explicit per-currency price overrides. */
|
|
43
|
+
readonly priceByCurrency?: MoneyByCurrency;
|
|
44
|
+
/** Optional cost (role-gated — filtered for non-finance readers). */
|
|
45
|
+
readonly costPrice?: Money;
|
|
46
|
+
/** Optional volume tiers (quantity-based discounts). */
|
|
47
|
+
readonly tiers?: readonly PriceTier[];
|
|
48
|
+
}
|
|
49
|
+
type DurationUnit = 'day' | 'week' | 'month' | 'year';
|
|
50
|
+
interface SubscriptionPlan {
|
|
51
|
+
/** Internal key ('monthly', 'quarterly', 'annual'). */
|
|
52
|
+
readonly key: string;
|
|
53
|
+
/** Display label ("Monthly", "Annual (save 20%)"). */
|
|
54
|
+
readonly label: string;
|
|
55
|
+
/** Base price for this plan in the default currency. */
|
|
56
|
+
readonly price: Money;
|
|
57
|
+
/** Explicit per-currency overrides. */
|
|
58
|
+
readonly priceByCurrency?: MoneyByCurrency;
|
|
59
|
+
/** Billing cycle length. */
|
|
60
|
+
readonly duration: number;
|
|
61
|
+
/** Unit of the billing cycle. */
|
|
62
|
+
readonly durationUnit: DurationUnit;
|
|
63
|
+
/** Optional free trial length in days. */
|
|
64
|
+
readonly trialDays?: number;
|
|
65
|
+
/** Optional auto-calculated discount vs the highest-frequency plan. */
|
|
66
|
+
readonly discount?: number;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* One band of a metered rate table.
|
|
70
|
+
*
|
|
71
|
+
* `upTo` is the inclusive upper bound of the band; omit it for the final,
|
|
72
|
+
* open-ended band. Within a band either a `perUnit` rate applies (per metered
|
|
73
|
+
* unit) or a `flatPrice` (a stairstep charge for landing in the band).
|
|
74
|
+
*/
|
|
75
|
+
interface UsageTier {
|
|
76
|
+
readonly upTo?: number;
|
|
77
|
+
readonly perUnit?: Money;
|
|
78
|
+
readonly flatPrice?: Money;
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* How a metered unit is priced. One `scheme`, composed with the fields it needs
|
|
82
|
+
* — this single shape covers per-seat, metered, graduated, volume, package and
|
|
83
|
+
* base-plus-overage without a separate kind for each.
|
|
84
|
+
*
|
|
85
|
+
* - `per_unit` — price × quantity (per-seat licensing, flat metering).
|
|
86
|
+
* - `tiered` — graduated: each unit priced at the rate of the band it falls in.
|
|
87
|
+
* - `volume` — the WHOLE quantity priced at the band the total lands in.
|
|
88
|
+
* - `package` — priced per package of `packageSize` units.
|
|
89
|
+
*
|
|
90
|
+
* `includedUnits` are free before metering starts (base-plus-overage when paired
|
|
91
|
+
* with {@link UsageMonetization.baseFee}).
|
|
92
|
+
*/
|
|
93
|
+
interface UsageRating {
|
|
94
|
+
readonly scheme: 'per_unit' | 'tiered' | 'volume' | 'package';
|
|
95
|
+
/** Flat per-unit rate (`per_unit` scheme). */
|
|
96
|
+
readonly perUnit?: Money;
|
|
97
|
+
/** Rate table (`tiered` / `volume` schemes). */
|
|
98
|
+
readonly tiers?: readonly UsageTier[];
|
|
99
|
+
/** Units per package and the package price (`package` scheme). */
|
|
100
|
+
readonly packageSize?: number;
|
|
101
|
+
readonly packagePrice?: Money;
|
|
102
|
+
/** Free units before metering starts (base-plus-overage). */
|
|
103
|
+
readonly includedUnits?: number;
|
|
104
|
+
/** Display label for one unit ("seat", "GB", "call", "visit"). */
|
|
105
|
+
readonly unitLabel?: string;
|
|
106
|
+
}
|
|
107
|
+
interface FreeMonetization {
|
|
108
|
+
readonly type: 'free';
|
|
109
|
+
}
|
|
110
|
+
interface OneTimeMonetization {
|
|
111
|
+
readonly type: 'one_time';
|
|
112
|
+
readonly pricing: OneTimePricing;
|
|
113
|
+
}
|
|
114
|
+
interface SubscriptionMonetization {
|
|
115
|
+
readonly type: 'subscription';
|
|
116
|
+
/** At least one plan is required. */
|
|
117
|
+
readonly plans: readonly SubscriptionPlan[];
|
|
118
|
+
}
|
|
119
|
+
interface BundleMonetization {
|
|
120
|
+
readonly type: 'bundle';
|
|
121
|
+
/** Optional fixed bundle price (overrides the dynamic sum). */
|
|
122
|
+
readonly basePrice?: Money;
|
|
123
|
+
/** How bundle pricing is computed. */
|
|
124
|
+
readonly pricingMode: 'fixed' | 'dynamic';
|
|
125
|
+
/** For `dynamic` mode, an optional 0–100 discount on the members' sum. */
|
|
126
|
+
readonly dynamicDiscountPercent?: number;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Metered / consumption pricing. The extension point for per-seat, metered,
|
|
130
|
+
* graduated, volume, package and base-plus-overage — all via {@link UsageRating}
|
|
131
|
+
* so the classification does not grow one kind per rating model.
|
|
132
|
+
*/
|
|
133
|
+
interface UsageMonetization {
|
|
134
|
+
readonly type: 'usage';
|
|
135
|
+
/** Optional recurring base fee charged regardless of usage (base + overage). */
|
|
136
|
+
readonly baseFee?: Money;
|
|
137
|
+
/** How each metered unit is priced. */
|
|
138
|
+
readonly rating: UsageRating;
|
|
139
|
+
/** Settlement cadence when usage is billed in arrears. */
|
|
140
|
+
readonly billingPeriod?: {
|
|
141
|
+
readonly duration: number;
|
|
142
|
+
readonly durationUnit: DurationUnit;
|
|
143
|
+
};
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* The canonical monetization value object. The `type` discriminant selects the
|
|
147
|
+
* pricing detail. Matches `@classytic/catalog`'s existing discriminants (so no
|
|
148
|
+
* data migration) plus `usage`.
|
|
149
|
+
*/
|
|
150
|
+
type Monetization = FreeMonetization | OneTimeMonetization | SubscriptionMonetization | BundleMonetization | UsageMonetization;
|
|
151
|
+
declare const isFreeMonetization: (m: Monetization) => m is FreeMonetization;
|
|
152
|
+
declare const isOneTimeMonetization: (m: Monetization) => m is OneTimeMonetization;
|
|
153
|
+
declare const isSubscriptionMonetization: (m: Monetization) => m is SubscriptionMonetization;
|
|
154
|
+
declare const isBundleMonetization: (m: Monetization) => m is BundleMonetization;
|
|
155
|
+
declare const isUsageMonetization: (m: Monetization) => m is UsageMonetization;
|
|
156
|
+
/** The kind of a monetization value (its discriminant, narrowed to the union). */
|
|
157
|
+
declare const monetizationKindOf: (m: Monetization) => MonetizationKind;
|
|
158
|
+
/**
|
|
159
|
+
* The single headline unit price for a monetization, or `null` when there isn't
|
|
160
|
+
* one. This is the ONE place that decides "which number is the price" per kind,
|
|
161
|
+
* so a cart line, an order snapshot and a storefront card never re-`switch` on
|
|
162
|
+
* `type` and drift (a host that read `plans[0].price` while another read
|
|
163
|
+
* `plans[1]` is exactly the divergence this prevents).
|
|
164
|
+
*
|
|
165
|
+
* - `one_time` → the base (list) price
|
|
166
|
+
* - `subscription` → the first plan's price (the default / most-frequent plan)
|
|
167
|
+
* - `bundle` → the FIXED bundle price; `null` in `dynamic` mode (that
|
|
168
|
+
* price is computed from the members, not stored here)
|
|
169
|
+
* - `free` → `null`
|
|
170
|
+
* - `usage` → `null` — a metered item has no single unit price; it is
|
|
171
|
+
* rated per consumption via {@link UsageRating}
|
|
172
|
+
*
|
|
173
|
+
* Exhaustive on purpose: a new kind fails to compile here until it declares how
|
|
174
|
+
* it prices, instead of silently returning `null`.
|
|
175
|
+
*/
|
|
176
|
+
declare function unitPriceOf(m: Monetization): Money | null;
|
|
177
|
+
/** The strikethrough / MSRP price, if the kind carries one (only `one_time`). */
|
|
178
|
+
declare function compareAtPriceOf(m: Monetization): Money | null;
|
|
179
|
+
/**
|
|
180
|
+
* `@classytic/revenue`'s coarse wire enum. `purchase` is the paid-once case that
|
|
181
|
+
* the rest of the ecosystem calls `one_time`. Kept as its own type so revenue's
|
|
182
|
+
* PERSISTED values never have to change — only the mapping to the canonical kind
|
|
183
|
+
* lives here, in one place, instead of an implicit hand-conversion per call site.
|
|
184
|
+
*/
|
|
185
|
+
type RevenueMonetizationType = 'free' | 'purchase' | 'subscription';
|
|
186
|
+
/**
|
|
187
|
+
* Canonical kind → revenue wire type. Everything that is not `free` or
|
|
188
|
+
* `subscription` settles as a `purchase` in revenue's ledger vocabulary
|
|
189
|
+
* (one_time, bundle, and a usage charge are all "a purchase happened").
|
|
190
|
+
*/
|
|
191
|
+
declare function toRevenueMonetizationType(kind: MonetizationKind): RevenueMonetizationType;
|
|
192
|
+
/** Revenue wire type → canonical kind (`purchase` → `one_time`). */
|
|
193
|
+
declare function fromRevenueMonetizationType(type: RevenueMonetizationType): MonetizationKind;
|
|
194
|
+
//#endregion
|
|
195
|
+
export { BundleMonetization, DurationUnit, FreeMonetization, MONETIZATION_KINDS, Monetization, MonetizationKind, MoneyByCurrency, OneTimeMonetization, OneTimePricing, PriceTier, RevenueMonetizationType, SubscriptionMonetization, SubscriptionPlan, UsageMonetization, UsageRating, UsageTier, compareAtPriceOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isSubscriptionMonetization, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
//#region src/money/monetization.ts
|
|
2
|
+
/**
|
|
3
|
+
* The canonical monetization kinds. Order is stable; append only.
|
|
4
|
+
*
|
|
5
|
+
* - `free` — no charge.
|
|
6
|
+
* - `one_time` — charged once (catalog `one_time`; revenue `purchase`).
|
|
7
|
+
* - `subscription` — recurring plan / membership.
|
|
8
|
+
* - `bundle` — a composite priced from its members.
|
|
9
|
+
* - `usage` — metered / per-seat / consumption (billed per unit or in
|
|
10
|
+
* arrears). The extension point for rating models.
|
|
11
|
+
*/
|
|
12
|
+
const MONETIZATION_KINDS = [
|
|
13
|
+
"free",
|
|
14
|
+
"one_time",
|
|
15
|
+
"subscription",
|
|
16
|
+
"bundle",
|
|
17
|
+
"usage"
|
|
18
|
+
];
|
|
19
|
+
const MONETIZATION_KIND_SET = new Set(MONETIZATION_KINDS);
|
|
20
|
+
/** True when `value` is one of the canonical kinds. */
|
|
21
|
+
function isMonetizationKind(value) {
|
|
22
|
+
return typeof value === "string" && MONETIZATION_KIND_SET.has(value);
|
|
23
|
+
}
|
|
24
|
+
const isFreeMonetization = (m) => m.type === "free";
|
|
25
|
+
const isOneTimeMonetization = (m) => m.type === "one_time";
|
|
26
|
+
const isSubscriptionMonetization = (m) => m.type === "subscription";
|
|
27
|
+
const isBundleMonetization = (m) => m.type === "bundle";
|
|
28
|
+
const isUsageMonetization = (m) => m.type === "usage";
|
|
29
|
+
/** The kind of a monetization value (its discriminant, narrowed to the union). */
|
|
30
|
+
const monetizationKindOf = (m) => m.type;
|
|
31
|
+
/**
|
|
32
|
+
* The single headline unit price for a monetization, or `null` when there isn't
|
|
33
|
+
* one. This is the ONE place that decides "which number is the price" per kind,
|
|
34
|
+
* so a cart line, an order snapshot and a storefront card never re-`switch` on
|
|
35
|
+
* `type` and drift (a host that read `plans[0].price` while another read
|
|
36
|
+
* `plans[1]` is exactly the divergence this prevents).
|
|
37
|
+
*
|
|
38
|
+
* - `one_time` → the base (list) price
|
|
39
|
+
* - `subscription` → the first plan's price (the default / most-frequent plan)
|
|
40
|
+
* - `bundle` → the FIXED bundle price; `null` in `dynamic` mode (that
|
|
41
|
+
* price is computed from the members, not stored here)
|
|
42
|
+
* - `free` → `null`
|
|
43
|
+
* - `usage` → `null` — a metered item has no single unit price; it is
|
|
44
|
+
* rated per consumption via {@link UsageRating}
|
|
45
|
+
*
|
|
46
|
+
* Exhaustive on purpose: a new kind fails to compile here until it declares how
|
|
47
|
+
* it prices, instead of silently returning `null`.
|
|
48
|
+
*/
|
|
49
|
+
function unitPriceOf(m) {
|
|
50
|
+
switch (m.type) {
|
|
51
|
+
case "one_time": return m.pricing.basePrice;
|
|
52
|
+
case "subscription": return m.plans[0]?.price ?? null;
|
|
53
|
+
case "bundle": return m.basePrice ?? null;
|
|
54
|
+
case "free":
|
|
55
|
+
case "usage": return null;
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
/** The strikethrough / MSRP price, if the kind carries one (only `one_time`). */
|
|
59
|
+
function compareAtPriceOf(m) {
|
|
60
|
+
return m.type === "one_time" ? m.pricing.compareAtPrice ?? null : null;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* Canonical kind → revenue wire type. Everything that is not `free` or
|
|
64
|
+
* `subscription` settles as a `purchase` in revenue's ledger vocabulary
|
|
65
|
+
* (one_time, bundle, and a usage charge are all "a purchase happened").
|
|
66
|
+
*/
|
|
67
|
+
function toRevenueMonetizationType(kind) {
|
|
68
|
+
if (kind === "free") return "free";
|
|
69
|
+
if (kind === "subscription") return "subscription";
|
|
70
|
+
return "purchase";
|
|
71
|
+
}
|
|
72
|
+
/** Revenue wire type → canonical kind (`purchase` → `one_time`). */
|
|
73
|
+
function fromRevenueMonetizationType(type) {
|
|
74
|
+
if (type === "free") return "free";
|
|
75
|
+
if (type === "subscription") return "subscription";
|
|
76
|
+
return "one_time";
|
|
77
|
+
}
|
|
78
|
+
//#endregion
|
|
79
|
+
export { MONETIZATION_KINDS, compareAtPriceOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isSubscriptionMonetization, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import { Money } from "./money.mjs";
|
|
2
|
+
|
|
3
|
+
//#region src/money/proration.d.ts
|
|
4
|
+
/**
|
|
5
|
+
* How to count days within a period.
|
|
6
|
+
*
|
|
7
|
+
* - `'whole_day'` (default) — integer calendar-day counts. Callers normalize
|
|
8
|
+
* `periodStart`/`periodEnd`/`asOf` to business-local midnight first, so this
|
|
9
|
+
* matches "day-of-month" proration (the Stripe default, how ~99% of SaaS
|
|
10
|
+
* bill). `periodDays` is clamped to `>= 1`.
|
|
11
|
+
* - `'exact'` — fractional wall-clock day counts (`ms / 86_400_000`). Use when
|
|
12
|
+
* cycles are short and a partial day must be billed precisely.
|
|
13
|
+
*/
|
|
14
|
+
type ProrationGranularity = 'whole_day' | 'exact';
|
|
15
|
+
/** The elapsed/remaining split of a billing period at a change instant. */
|
|
16
|
+
interface PeriodFraction {
|
|
17
|
+
/** Total days in the period. `>= 1` for `whole_day`; `> 0` for `exact`. */
|
|
18
|
+
readonly periodDays: number;
|
|
19
|
+
/** Days consumed as of the change instant, clamped to `[0, periodDays]`. */
|
|
20
|
+
readonly elapsedDays: number;
|
|
21
|
+
/** `periodDays - elapsedDays`. */
|
|
22
|
+
readonly remainingDays: number;
|
|
23
|
+
/** `remainingDays / periodDays`, in `[0, 1]`. */
|
|
24
|
+
readonly remainingFraction: number;
|
|
25
|
+
}
|
|
26
|
+
interface PeriodProgressInput {
|
|
27
|
+
/** Period start instant (business-tz-normalized by the caller). */
|
|
28
|
+
readonly periodStart: Date;
|
|
29
|
+
/** Period end instant — must be strictly after `periodStart`. */
|
|
30
|
+
readonly periodEnd: Date;
|
|
31
|
+
/** The change/quote instant. Clamped into `[periodStart, periodEnd]`. */
|
|
32
|
+
readonly asOf: Date;
|
|
33
|
+
/** Day-counting granularity. Default `'whole_day'`. */
|
|
34
|
+
readonly granularity?: ProrationGranularity;
|
|
35
|
+
}
|
|
36
|
+
type ProrationErrorCode = 'INVALID_PERIOD' | 'INVALID_FRACTION';
|
|
37
|
+
declare class ProrationError extends Error {
|
|
38
|
+
readonly name = "ProrationError";
|
|
39
|
+
readonly code: ProrationErrorCode;
|
|
40
|
+
constructor(code: ProrationErrorCode, message: string);
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Compute how much of a period is elapsed vs remaining at `asOf`.
|
|
44
|
+
*
|
|
45
|
+
* `asOf` before the period start ⇒ nothing elapsed (full remaining);
|
|
46
|
+
* `asOf` after the period end ⇒ fully elapsed (nothing remaining).
|
|
47
|
+
*
|
|
48
|
+
* @throws ProrationError('INVALID_PERIOD') if a date is invalid or
|
|
49
|
+
* `periodEnd <= periodStart`.
|
|
50
|
+
*/
|
|
51
|
+
declare function periodProgress(input: PeriodProgressInput): PeriodFraction;
|
|
52
|
+
/**
|
|
53
|
+
* Split a `Money` amount into its consumed and remaining parts across a
|
|
54
|
+
* {@link PeriodFraction}, drift-free: `consumed.amount + remaining.amount ===
|
|
55
|
+
* amount.amount` exactly (largest-remainder allocation). Sign is preserved, so
|
|
56
|
+
* a negative amount (a reversal) splits symmetrically.
|
|
57
|
+
*
|
|
58
|
+
* This is the load-bearing primitive for proration: the "unused value" a
|
|
59
|
+
* plan-change credits is `remaining`; the "already-consumed value" is
|
|
60
|
+
* `consumed`.
|
|
61
|
+
*/
|
|
62
|
+
declare function splitByPeriodFraction(amount: Money, fraction: PeriodFraction): {
|
|
63
|
+
readonly consumed: Money;
|
|
64
|
+
readonly remaining: Money;
|
|
65
|
+
};
|
|
66
|
+
/**
|
|
67
|
+
* Allocate the `fraction`-weighted part of a `Money` amount, drift-free — the
|
|
68
|
+
* complement (`1 - fraction`) is discarded but computed so rounding is exact
|
|
69
|
+
* against the whole. `fraction` must be in `[0, 1]`.
|
|
70
|
+
*
|
|
71
|
+
* @throws ProrationError('INVALID_FRACTION') if `fraction` is outside `[0, 1]`
|
|
72
|
+
* or not finite.
|
|
73
|
+
*/
|
|
74
|
+
declare function allocateMoneyByFraction(amount: Money, fraction: number): Money;
|
|
75
|
+
//#endregion
|
|
76
|
+
export { PeriodFraction, PeriodProgressInput, ProrationError, ProrationErrorCode, ProrationGranularity, allocateMoneyByFraction, periodProgress, splitByPeriodFraction };
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
import { allocate } from "./split-allocation.mjs";
|
|
2
|
+
//#region src/money/proration.ts
|
|
3
|
+
/**
|
|
4
|
+
* Pure proration ARITHMETIC — fraction / period / allocation / rounding only.
|
|
5
|
+
*
|
|
6
|
+
* This module deliberately holds **no commercial policy**. It does not know
|
|
7
|
+
* what "an upgrade" is, whether a discount is creditable, how tax is treated,
|
|
8
|
+
* or whether a downgrade yields cash vs store credit. Those decisions live in
|
|
9
|
+
* the subscription/contract kernel (`@classytic/contract`
|
|
10
|
+
* `calculatePlanChangeProration(...)`), which composes these primitives.
|
|
11
|
+
*
|
|
12
|
+
* It is also **timezone-agnostic**: callers pass already-resolved `Date`
|
|
13
|
+
* instants (normalized to the deployment's business timezone via
|
|
14
|
+
* `@classytic/primitives/timezone` upstream). This module never reads a clock
|
|
15
|
+
* and never applies an offset — pass instants, get numbers.
|
|
16
|
+
*
|
|
17
|
+
* Money is integer minor units throughout; splits use the largest-remainder
|
|
18
|
+
* allocator so `consumed + remaining === amount` exactly, with no penny drift.
|
|
19
|
+
*/
|
|
20
|
+
const MS_PER_DAY = 864e5;
|
|
21
|
+
var ProrationError = class extends Error {
|
|
22
|
+
name = "ProrationError";
|
|
23
|
+
code;
|
|
24
|
+
constructor(code, message) {
|
|
25
|
+
super(message);
|
|
26
|
+
this.code = code;
|
|
27
|
+
}
|
|
28
|
+
};
|
|
29
|
+
function isValidDate(d) {
|
|
30
|
+
return d instanceof Date && !Number.isNaN(d.getTime());
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Compute how much of a period is elapsed vs remaining at `asOf`.
|
|
34
|
+
*
|
|
35
|
+
* `asOf` before the period start ⇒ nothing elapsed (full remaining);
|
|
36
|
+
* `asOf` after the period end ⇒ fully elapsed (nothing remaining).
|
|
37
|
+
*
|
|
38
|
+
* @throws ProrationError('INVALID_PERIOD') if a date is invalid or
|
|
39
|
+
* `periodEnd <= periodStart`.
|
|
40
|
+
*/
|
|
41
|
+
function periodProgress(input) {
|
|
42
|
+
const { periodStart, periodEnd, asOf, granularity = "whole_day" } = input;
|
|
43
|
+
if (!isValidDate(periodStart) || !isValidDate(periodEnd) || !isValidDate(asOf)) throw new ProrationError("INVALID_PERIOD", "periodStart, periodEnd and asOf must be valid Dates");
|
|
44
|
+
const startMs = periodStart.getTime();
|
|
45
|
+
const endMs = periodEnd.getTime();
|
|
46
|
+
if (endMs <= startMs) throw new ProrationError("INVALID_PERIOD", `periodEnd (${periodEnd.toISOString()}) must be after periodStart (${periodStart.toISOString()})`);
|
|
47
|
+
const clampedAsOfMs = Math.min(Math.max(asOf.getTime(), startMs), endMs);
|
|
48
|
+
const rawPeriodDays = (endMs - startMs) / MS_PER_DAY;
|
|
49
|
+
const rawElapsedDays = (clampedAsOfMs - startMs) / MS_PER_DAY;
|
|
50
|
+
let periodDays;
|
|
51
|
+
let elapsedDays;
|
|
52
|
+
if (granularity === "whole_day") {
|
|
53
|
+
periodDays = Math.max(1, Math.round(rawPeriodDays));
|
|
54
|
+
elapsedDays = Math.min(periodDays, Math.max(0, Math.round(rawElapsedDays)));
|
|
55
|
+
} else {
|
|
56
|
+
periodDays = rawPeriodDays;
|
|
57
|
+
elapsedDays = Math.min(periodDays, Math.max(0, rawElapsedDays));
|
|
58
|
+
}
|
|
59
|
+
const remainingDays = periodDays - elapsedDays;
|
|
60
|
+
return {
|
|
61
|
+
periodDays,
|
|
62
|
+
elapsedDays,
|
|
63
|
+
remainingDays,
|
|
64
|
+
remainingFraction: remainingDays / periodDays
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Split a `Money` amount into its consumed and remaining parts across a
|
|
69
|
+
* {@link PeriodFraction}, drift-free: `consumed.amount + remaining.amount ===
|
|
70
|
+
* amount.amount` exactly (largest-remainder allocation). Sign is preserved, so
|
|
71
|
+
* a negative amount (a reversal) splits symmetrically.
|
|
72
|
+
*
|
|
73
|
+
* This is the load-bearing primitive for proration: the "unused value" a
|
|
74
|
+
* plan-change credits is `remaining`; the "already-consumed value" is
|
|
75
|
+
* `consumed`.
|
|
76
|
+
*/
|
|
77
|
+
function splitByPeriodFraction(amount, fraction) {
|
|
78
|
+
const result = allocate(amount.amount, [{
|
|
79
|
+
id: "consumed",
|
|
80
|
+
weight: fraction.elapsedDays
|
|
81
|
+
}, {
|
|
82
|
+
id: "remaining",
|
|
83
|
+
weight: fraction.remainingDays
|
|
84
|
+
}], "by-weight");
|
|
85
|
+
const consumed = result.parts.find((p) => p.id === "consumed")?.amount ?? 0;
|
|
86
|
+
const remaining = result.parts.find((p) => p.id === "remaining")?.amount ?? 0;
|
|
87
|
+
return {
|
|
88
|
+
consumed: {
|
|
89
|
+
amount: consumed,
|
|
90
|
+
currency: amount.currency
|
|
91
|
+
},
|
|
92
|
+
remaining: {
|
|
93
|
+
amount: remaining,
|
|
94
|
+
currency: amount.currency
|
|
95
|
+
}
|
|
96
|
+
};
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* Allocate the `fraction`-weighted part of a `Money` amount, drift-free — the
|
|
100
|
+
* complement (`1 - fraction`) is discarded but computed so rounding is exact
|
|
101
|
+
* against the whole. `fraction` must be in `[0, 1]`.
|
|
102
|
+
*
|
|
103
|
+
* @throws ProrationError('INVALID_FRACTION') if `fraction` is outside `[0, 1]`
|
|
104
|
+
* or not finite.
|
|
105
|
+
*/
|
|
106
|
+
function allocateMoneyByFraction(amount, fraction) {
|
|
107
|
+
if (!Number.isFinite(fraction) || fraction < 0 || fraction > 1) throw new ProrationError("INVALID_FRACTION", `fraction must be in [0, 1], got ${fraction}`);
|
|
108
|
+
return {
|
|
109
|
+
amount: allocate(amount.amount, [{
|
|
110
|
+
id: "part",
|
|
111
|
+
weight: fraction
|
|
112
|
+
}, {
|
|
113
|
+
id: "rest",
|
|
114
|
+
weight: 1 - fraction
|
|
115
|
+
}], "by-weight").parts.find((p) => p.id === "part")?.amount ?? 0,
|
|
116
|
+
currency: amount.currency
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
//#endregion
|
|
120
|
+
export { ProrationError, allocateMoneyByFraction, periodProgress, splitByPeriodFraction };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@classytic/primitives",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.19.0",
|
|
4
4
|
"description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
|
|
5
5
|
"author": "Classytic",
|
|
6
6
|
"license": "MIT",
|
|
@@ -133,6 +133,14 @@
|
|
|
133
133
|
"types": "./dist/payment-allocation-status.d.mts",
|
|
134
134
|
"default": "./dist/payment-allocation-status.mjs"
|
|
135
135
|
},
|
|
136
|
+
"./monetization": {
|
|
137
|
+
"types": "./dist/monetization.d.mts",
|
|
138
|
+
"default": "./dist/monetization.mjs"
|
|
139
|
+
},
|
|
140
|
+
"./proration": {
|
|
141
|
+
"types": "./dist/proration.d.mts",
|
|
142
|
+
"default": "./dist/proration.mjs"
|
|
143
|
+
},
|
|
136
144
|
"./payment-events": {
|
|
137
145
|
"types": "./dist/payment-events.d.mts",
|
|
138
146
|
"default": "./dist/payment-events.mjs"
|