@softure-ai/billing 0.0.0-stage → 0.1.5

package/dist/plans.d.ts

@@ -0,0 +1,20 @@
+import type { Locale } from "@softure-ai/core";
+import type { EntitlementEvent, EntitlementRecord, LocalizedText, Plan, PlanPeriod } from "./contract.js";
+/** The text in `locale`, else the `en` text (the options require one). */
+export declare function getLocalizedText(text: LocalizedText, locale: Locale): string;
+/** The plan with this id, or undefined. */
+export declare function findPlan(plans: readonly Plan[], planId: string): Plan | undefined;
+/**
+ * The end of one period begun at `start`: the start of the local day one period after the start
+ * day. The start day counts as the first day, as for trials. Lifetime periods have no end.
+ */
+export declare function getPeriodEnd(start: Date, period: Exclude<PlanPeriod, {
+    unit: "lifetime";
+}>, timezone: string): Date;
+/**
+ * The change one payment of `plan` makes to `record` at `now`. A paid period starts when the access
+ * the account already has ends (a running trial or paid access), so paying early loses no day; a
+ * lifetime plan grants lifetime access.
+ */
+export declare function getPlanGrant(record: EntitlementRecord, plan: Plan, now: Date, timezone: string): EntitlementEvent;
+//# sourceMappingURL=plans.d.ts.map

package/dist/plans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plans.d.ts","sourceRoot":"","sources":["../src/plans.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAM1G,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED,2CAA2C;AAC3C,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAEjF;AAWD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAYnH;AAOD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAIjH"}

package/dist/plans.js

@@ -0,0 +1,53 @@
+import { getDayNumber, getStartOfDay } from "./calendar.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DAYS_PER_WEEK = 7;
+const MONTHS_PER_YEAR = 12;
+/** The text in `locale`, else the `en` text (the options require one). */
+export function getLocalizedText(text, locale) {
+    return text[locale] ?? text.en ?? "";
+}
+/** The plan with this id, or undefined. */
+export function findPlan(plans, planId) {
+    return plans.find((plan) => plan.id === planId);
+}
+/** A day number `months` calendar months later; a day the target month lacks becomes its last day. */
+function addMonths(dayNumber, months) {
+    const date = new Date(dayNumber * DAY_MS);
+    const year = date.getUTCFullYear();
+    const month = date.getUTCMonth() + months;
+    const lastDay = new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+    return Math.floor(Date.UTC(year, month, Math.min(date.getUTCDate(), lastDay)) / DAY_MS);
+}
+/**
+ * The end of one period begun at `start`: the start of the local day one period after the start
+ * day. The start day counts as the first day, as for trials. Lifetime periods have no end.
+ */
+export function getPeriodEnd(start, period, timezone) {
+    const day = getDayNumber(start, timezone);
+    switch (period.unit) {
+        case "day":
+            return getStartOfDay(day + period.count, timezone);
+        case "week":
+            return getStartOfDay(day + period.count * DAYS_PER_WEEK, timezone);
+        case "month":
+            return getStartOfDay(addMonths(day, period.count), timezone);
+        case "year":
+            return getStartOfDay(addMonths(day, period.count * MONTHS_PER_YEAR), timezone);
+    }
+}
+/** The latest of some instants. */
+function getLatest(first, ...rest) {
+    return rest.reduce((latest, instant) => (instant > latest ? instant : latest), first);
+}
+/**
+ * The change one payment of `plan` makes to `record` at `now`. A paid period starts when the access
+ * the account already has ends (a running trial or paid access), so paying early loses no day; a
+ * lifetime plan grants lifetime access.
+ */
+export function getPlanGrant(record, plan, now, timezone) {
+    if (plan.period.unit === "lifetime")
+        return { type: "grant_lifetime" };
+    const start = getLatest(now, record.trialEndsAt, ...(record.paidUntil === null ? [] : [record.paidUntil]));
+    return { type: "grant", until: getPeriodEnd(start, plan.period, timezone) };
+}
+//# sourceMappingURL=plans.js.map

package/dist/plans.js.map

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

package/dist/price.d.ts

@@ -0,0 +1,12 @@
+import type { Locale } from "@softure-ai/core";
+import type { PlanPrice } from "./contract.js";
+/** Whether billing accepts `currency`: an upper-case ISO 4217 code in its pinned table. */
+export declare function isSupportedCurrency(currency: string): boolean;
+/** Digits of the currency's minor unit: 2 for PLN, EUR and HUF, 0 for JPY, 3 for KWD. */
+export declare function getMinorUnitDigits(currency: string): number;
+/**
+ * The price in the locale's notation, e.g. "PLN 29.00" in en. A stored price in a code billing no
+ * longer accepts is shown with `Intl`'s own digits, so a history page never breaks on it.
+ */
+export declare function formatPrice(price: PlanPrice, locale: Locale): string;
+//# sourceMappingURL=price.d.ts.map

package/dist/price.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"price.d.ts","sourceRoot":"","sources":["../src/price.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAuB/C,2FAA2F;AAC3F,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED,yFAAyF;AACzF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK3D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAIpE"}

package/dist/price.js

@@ -0,0 +1,37 @@
+import { CURRENCY_MINOR_UNIT_DIGITS } from "./currency-digits.js";
+const formatters = new Map();
+/** The pinned digits, or undefined for a code billing does not accept. */
+function findMinorUnitDigits(currency) {
+    return Object.hasOwn(CURRENCY_MINOR_UNIT_DIGITS, currency) ? CURRENCY_MINOR_UNIT_DIGITS[currency] : undefined;
+}
+function getFormatter(locale, currency, digits) {
+    const key = `${locale}:${currency}`;
+    let format = formatters.get(key);
+    if (format === undefined) {
+        format = new Intl.NumberFormat(locale, digits === undefined ? { style: "currency", currency } : { style: "currency", currency, minimumFractionDigits: digits, maximumFractionDigits: digits });
+        formatters.set(key, format);
+    }
+    return format;
+}
+/** Whether billing accepts `currency`: an upper-case ISO 4217 code in its pinned table. */
+export function isSupportedCurrency(currency) {
+    return findMinorUnitDigits(currency) !== undefined;
+}
+/** Digits of the currency's minor unit: 2 for PLN, EUR and HUF, 0 for JPY, 3 for KWD. */
+export function getMinorUnitDigits(currency) {
+    const digits = findMinorUnitDigits(currency);
+    // A config with this code is refused when it loads, so reaching here is a bug.
+    if (digits === undefined)
+        throw new Error(`getMinorUnitDigits: billing does not know the currency "${currency}"`);
+    return digits;
+}
+/**
+ * The price in the locale's notation, e.g. "PLN 29.00" in en. A stored price in a code billing no
+ * longer accepts is shown with `Intl`'s own digits, so a history page never breaks on it.
+ */
+export function formatPrice(price, locale) {
+    const digits = findMinorUnitDigits(price.currency);
+    const format = getFormatter(locale, price.currency, digits);
+    return format.format(price.amount / 10 ** (digits ?? format.resolvedOptions().maximumFractionDigits ?? 2));
+}
+//# sourceMappingURL=price.js.map

package/dist/price.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"price.js","sourceRoot":"","sources":["../src/price.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAElE,MAAM,UAAU,GAAG,IAAI,GAAG,EAA6B,CAAC;AAExD,0EAA0E;AAC1E,SAAS,mBAAmB,CAAC,QAAgB;IAC3C,OAAO,MAAM,CAAC,MAAM,CAAC,0BAA0B,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,0BAA0B,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAChH,CAAC;AAED,SAAS,YAAY,CAAC,MAAc,EAAE,QAAgB,EAAE,MAA0B;IAChF,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,QAAQ,EAAE,CAAC;IACpC,IAAI,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,GAAG,IAAI,IAAI,CAAC,YAAY,CAC5B,MAAM,EACN,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,EAAE,CACvJ,CAAC;QACF,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IAClD,OAAO,mBAAmB,CAAC,QAAQ,CAAC,KAAK,SAAS,CAAC;AACrD,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,MAAM,MAAM,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAC7C,+EAA+E;IAC/E,IAAI,MAAM,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,2DAA2D,QAAQ,GAAG,CAAC,CAAC;IAClH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAgB,EAAE,MAAc;IAC1D,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC5D,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,EAAE,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC,qBAAqB,IAAI,CAAC,CAAC,CAAC,CAAC;AAC7G,CAAC"}

package/dist/refund.d.ts

@@ -0,0 +1,70 @@
+import type { EntitlementEvent, EntitlementRecord, PaymentGrant } from "./contract.js";
+/** Where a grant added to `record` at `now` starts: the latest of the trial's end, dated paid access and `now`. */
+export declare function getGrantStart(record: EntitlementRecord, now: Date): Date;
+/**
+ * What a plan's event added to `record`: the period from where access ended (the trial, dated paid
+ * access or `now`, as `getPlanGrant` starts it) to the event's end, or lifetime access. Null for an
+ * event that is not a plan grant.
+ */
+export declare function getPaymentGrant(record: EntitlementRecord, event: EntitlementEvent, now: Date): PaymentGrant | null;
+/**
+ * `instant` moved back by `days` local days in `timezone`, at the same local time of day (the first
+ * instant of the day when that time does not exist there).
+ */
+export declare function moveBackByDays(instant: Date, days: number, timezone: string): Date;
+/**
+ * The local days of a period not used yet at `now`, `[max(from, now), until)`, today included; 0
+ * once the period has ended. A refund moves dated access, and every period stacked after this one,
+ * back by this many days.
+ */
+export declare function getUnusedDays(grant: Extract<PaymentGrant, {
+    kind: "period";
+}>, now: Date, timezone: string): number;
+/** The part of a payment a refund returns: `refunded` newly refunded out of the `outstanding` amount not refunded before. */
+export interface RefundShare {
+    readonly refunded: number;
+    readonly outstanding: number;
+}
+export interface RefundTiming {
+    readonly now: Date;
+    readonly timezone: string;
+    /** The part of the payment refunded; omitted for a full refund. */
+    readonly share?: RefundShare;
+}
+/** Whether `share` returns everything not refunded before (or is absent: a full refund). */
+export declare function isFullShare(share: RefundShare | undefined): boolean;
+/**
+ * The local days a refund takes back from a period: all its unused days (`getUnusedDays`) for a
+ * full share, else that share of them rounded down, so the account keeps any part of a day.
+ */
+export declare function getTakenBackDays(grant: Extract<PaymentGrant, {
+    kind: "period";
+}>, timing: RefundTiming): number;
+/**
+ * The change a refund of a payment that granted `grant` makes to `record`: a period moves dated
+ * paid access back by the days it takes back (`getTakenBackDays`), and a full refund of a lifetime
+ * ends lifetime access. Null when nothing is taken back (the period is used up, the share rounds to
+ * no day, a partial refund of a lifetime, or dated access is already gone).
+ */
+export declare function getRefundEvent(record: EntitlementRecord, grant: PaymentGrant, timing: RefundTiming): EntitlementEvent | null;
+/** `instant` moved forward by `days` local days in `timezone`, as `moveBackByDays` moves it back. */
+export declare function moveForwardByDays(instant: Date, days: number, timezone: string): Date;
+export interface RestoredDaysInput {
+    /** The local days refunds took from the payment's period so far. */
+    readonly takenBackDays: number;
+    /** The payment's refunded total before the failure. */
+    readonly refundedAmount: number;
+    /** The part of that total the failure gives back (at most `refundedAmount`). */
+    readonly restoredAmount: number;
+    /** The app's `partialRefunds` policy. */
+    readonly policy: "pro_rata" | "keep_access";
+}
+/**
+ * The local days a failed refund gives back. Under `pro_rata` the share of the days refunds took
+ * that the failed money is of the money refunded, rounded down, and every day once nothing stays
+ * refunded, so failures that undo every refund give back exactly what was taken. Under
+ * `keep_access` only the refund that completed the payment took days, so any failure gives them
+ * all back: the payment is no longer refunded in full.
+ */
+export declare function getRestoredDays({ takenBackDays, refundedAmount, restoredAmount, policy }: RestoredDaysInput): number;
+//# sourceMappingURL=refund.d.ts.map

package/dist/refund.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refund.d.ts","sourceRoot":"","sources":["../src/refund.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAOvF,mHAAmH;AACnH,wBAAgB,aAAa,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,IAAI,GAAG,IAAI,CAExE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,IAAI,GAAG,YAAY,GAAG,IAAI,CAWlH;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAIlF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGnH;AAED,6HAA6H;AAC7H,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAEnE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CAO/G;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,GAAG,gBAAgB,GAAG,IAAI,CAK5H;AAED,qGAAqG;AACrG,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAErF;AAED,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,gFAAgF;IAChF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,EAAE,EAAE,iBAAiB,GAAG,MAAM,CAOpH"}

package/dist/refund.js

@@ -0,0 +1,109 @@
+// Refunds, pure: what one payment of a plan added to an account (stored with the payment) and the
+// change a refund of it makes. A full refund takes back the part of the payment's period not used
+// yet. Access ahead of now is one unbroken run (every grant starts where running access ends), so
+// taking back those days moves the dated end back by as many local days; a period already used up
+// takes nothing back, and a lapse between payments never lets an old refund eat a new period.
+// A partial refund takes back the same share of those days as the share of the money not refunded
+// before that it returns, rounded down: the refund that completes the amount has a share of one, so
+// partial refunds that add up to the whole payment take back what one full refund would. A refund
+// that fails later gives back the failed money's share of the days refunds took.
+import { getDayNumber, getStartOfDay } from "./calendar.js";
+/** The later of two instants. */
+function getLater(first, second) {
+    return first > second ? first : second;
+}
+/** Where a grant added to `record` at `now` starts: the latest of the trial's end, dated paid access and `now`. */
+export function getGrantStart(record, now) {
+    return [record.trialEndsAt, ...(record.paidUntil === null ? [] : [record.paidUntil])].reduce(getLater, now);
+}
+/**
+ * What a plan's event added to `record`: the period from where access ended (the trial, dated paid
+ * access or `now`, as `getPlanGrant` starts it) to the event's end, or lifetime access. Null for an
+ * event that is not a plan grant.
+ */
+export function getPaymentGrant(record, event, now) {
+    switch (event.type) {
+        case "grant_lifetime":
+            return { kind: "lifetime" };
+        case "grant": {
+            const from = getGrantStart(record, now);
+            return from < event.until ? { kind: "period", from, until: event.until } : null;
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * `instant` moved back by `days` local days in `timezone`, at the same local time of day (the first
+ * instant of the day when that time does not exist there).
+ */
+export function moveBackByDays(instant, days, timezone) {
+    const day = getDayNumber(instant, timezone);
+    const timeOfDay = instant.getTime() - getStartOfDay(day, timezone).getTime();
+    return new Date(getStartOfDay(day - days, timezone).getTime() + timeOfDay);
+}
+/**
+ * The local days of a period not used yet at `now`, `[max(from, now), until)`, today included; 0
+ * once the period has ended. A refund moves dated access, and every period stacked after this one,
+ * back by this many days.
+ */
+export function getUnusedDays(grant, now, timezone) {
+    if (grant.until <= now)
+        return 0;
+    return Math.max(0, getDayNumber(grant.until, timezone) - getDayNumber(getLater(grant.from, now), timezone));
+}
+/** Whether `share` returns everything not refunded before (or is absent: a full refund). */
+export function isFullShare(share) {
+    return share === undefined || share.refunded >= share.outstanding;
+}
+/**
+ * The local days a refund takes back from a period: all its unused days (`getUnusedDays`) for a
+ * full share, else that share of them rounded down, so the account keeps any part of a day.
+ */
+export function getTakenBackDays(grant, timing) {
+    const unusedDays = getUnusedDays(grant, timing.now, timing.timezone);
+    const { share } = timing;
+    if (share === undefined || isFullShare(share))
+        return unusedDays;
+    if (share.refunded <= 0)
+        return 0;
+    // Integers: at most 10^8 minor units times a period's days stays a safe integer.
+    return Math.floor((unusedDays * share.refunded) / share.outstanding);
+}
+/**
+ * The change a refund of a payment that granted `grant` makes to `record`: a period moves dated
+ * paid access back by the days it takes back (`getTakenBackDays`), and a full refund of a lifetime
+ * ends lifetime access. Null when nothing is taken back (the period is used up, the share rounds to
+ * no day, a partial refund of a lifetime, or dated access is already gone).
+ */
+export function getRefundEvent(record, grant, timing) {
+    if (grant.kind === "lifetime")
+        return isFullShare(timing.share) ? { type: "end_lifetime" } : null;
+    const days = getTakenBackDays(grant, timing);
+    if (record.paidUntil === null || days === 0)
+        return null;
+    return { type: "shorten", until: moveBackByDays(record.paidUntil, days, timing.timezone) };
+}
+/** `instant` moved forward by `days` local days in `timezone`, as `moveBackByDays` moves it back. */
+export function moveForwardByDays(instant, days, timezone) {
+    return moveBackByDays(instant, -days, timezone);
+}
+/**
+ * The local days a failed refund gives back. Under `pro_rata` the share of the days refunds took
+ * that the failed money is of the money refunded, rounded down, and every day once nothing stays
+ * refunded, so failures that undo every refund give back exactly what was taken. Under
+ * `keep_access` only the refund that completed the payment took days, so any failure gives them
+ * all back: the payment is no longer refunded in full.
+ */
+export function getRestoredDays({ takenBackDays, refundedAmount, restoredAmount, policy }) {
+    if (takenBackDays <= 0 || restoredAmount <= 0 || refundedAmount <= 0)
+        return 0;
+    const remaining = refundedAmount - restoredAmount;
+    if (remaining <= 0)
+        return takenBackDays;
+    if (policy === "keep_access")
+        return takenBackDays;
+    // Integers: at most 10^8 minor units times a period's days stays a safe integer.
+    return Math.floor((takenBackDays * restoredAmount) / refundedAmount);
+}
+//# sourceMappingURL=refund.js.map

package/dist/refund.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refund.js","sourceRoot":"","sources":["../src/refund.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,kGAAkG;AAClG,kGAAkG;AAClG,kGAAkG;AAClG,8FAA8F;AAC9F,kGAAkG;AAClG,oGAAoG;AACpG,kGAAkG;AAClG,iFAAiF;AACjF,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG5D,iCAAiC;AACjC,SAAS,QAAQ,CAAC,KAAW,EAAE,MAAY;IACzC,OAAO,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;AACzC,CAAC;AAED,mHAAmH;AACnH,MAAM,UAAU,aAAa,CAAC,MAAyB,EAAE,GAAS;IAChE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AAC9G,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAyB,EAAE,KAAuB,EAAE,GAAS;IAC3F,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,gBAAgB;YACnB,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QAC9B,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YACxC,OAAO,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAClF,CAAC;QACD;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,OAAa,EAAE,IAAY,EAAE,QAAgB;IAC1E,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,aAAa,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC;IAC7E,OAAO,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,GAAG,IAAI,EAAE,QAAQ,CAAC,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,CAAC;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAgD,EAAE,GAAS,EAAE,QAAgB;IACzG,IAAI,KAAK,CAAC,KAAK,IAAI,GAAG;QAAE,OAAO,CAAC,CAAC;IACjC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC9G,CAAC;AAeD,4FAA4F;AAC5F,MAAM,UAAU,WAAW,CAAC,KAA8B;IACxD,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,WAAW,CAAC;AACpE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAgD,EAAE,MAAoB;IACrG,MAAM,UAAU,GAAG,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IACzB,IAAI,KAAK,KAAK,SAAS,IAAI,WAAW,CAAC,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC;IACjE,IAAI,KAAK,CAAC,QAAQ,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAClC,iFAAiF;IACjF,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,UAAU,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;AACvE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,MAAyB,EAAE,KAAmB,EAAE,MAAoB;IACjG,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAClG,MAAM,IAAI,GAAG,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC7C,IAAI,MAAM,CAAC,SAAS,KAAK,IAAI,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,cAAc,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;AAC7F,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,iBAAiB,CAAC,OAAa,EAAE,IAAY,EAAE,QAAgB;IAC7E,OAAO,cAAc,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAClD,CAAC;AAaD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,EAAqB;IAC1G,IAAI,aAAa,IAAI,CAAC,IAAI,cAAc,IAAI,CAAC,IAAI,cAAc,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC/E,MAAM,SAAS,GAAG,cAAc,GAAG,cAAc,CAAC;IAClD,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,aAAa,CAAC;IACzC,IAAI,MAAM,KAAK,aAAa;QAAE,OAAO,aAAa,CAAC;IACnD,iFAAiF;IACjF,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,aAAa,GAAG,cAAc,CAAC,GAAG,cAAc,CAAC,CAAC;AACvE,CAAC"}

package/dist/reminder.d.ts

@@ -0,0 +1,30 @@
+import type { EntitlementRecord } from "./contract.js";
+import { type EntitlementPolicy } from "./entitlement.js";
+export declare const ACCESS_REMINDER_KINDS: readonly ["trial-ending", "paid-ending", "trial-ended", "paid-ended"];
+export type AccessReminderKind = (typeof ACCESS_REMINDER_KINDS)[number];
+/** The longest catch-up window for ended mails, in days. */
+export declare const MAX_CATCH_UP_DAYS = 365;
+/** Days after the day access ended during which its ended mail is still due. */
+export declare const DEFAULT_CATCH_UP_DAYS = 3;
+export interface AccessReminder {
+    readonly kind: AccessReminderKind;
+    /** The first instant without the access the mail is about. */
+    readonly endsAt: Date;
+}
+export interface AccessReminderInput {
+    readonly record: EntitlementRecord;
+    /** `auth.users.created_at`: a trial that ended by then was never a trial. */
+    readonly accountCreatedAt: Date;
+    readonly now: Date;
+    readonly policy: EntitlementPolicy;
+    /** An ended mail is due from the day access ended through this many local days after it. */
+    readonly catchUpDays: number;
+}
+/** The reminder `input.record` is due at `input.now`, or null (lifetime, outside every window). */
+export declare function getAccessReminder(input: AccessReminderInput): AccessReminder | null;
+/**
+ * The delivery scope of a reminder in `mailing.deliveries`: one mail per account, kind and end, so
+ * a new end (an extended trial, a renewal, a refund) is a new window and the same end never mails twice.
+ */
+export declare function getAccessReminderScope(kind: AccessReminderKind, userId: string, endsAt: Date): string;
+//# sourceMappingURL=reminder.d.ts.map

package/dist/reminder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminder.d.ts","sourceRoot":"","sources":["../src/reminder.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE9E,eAAO,MAAM,qBAAqB,uEAAwE,CAAC;AAC3G,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,6EAA6E;IAC7E,QAAQ,CAAC,gBAAgB,EAAE,IAAI,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,mGAAmG;AACnG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,GAAG,cAAc,GAAG,IAAI,CAUnF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAG,MAAM,CAErG"}

package/dist/reminder.js

@@ -0,0 +1,34 @@
+// Which reminder mail an account is due, as a pure rule: the four states the in-app notice shows
+// (trial or paid access ending, trial or paid access ended), decided from the account's record by
+// the state machine. An ended mail is due only for a few days after the end, so turning reminders
+// on never mails every account that lapsed long ago.
+import { getDayNumber } from "./calendar.js";
+import { resolveEntitlement } from "./entitlement.js";
+export const ACCESS_REMINDER_KINDS = ["trial-ending", "paid-ending", "trial-ended", "paid-ended"];
+/** The longest catch-up window for ended mails, in days. */
+export const MAX_CATCH_UP_DAYS = 365;
+/** Days after the day access ended during which its ended mail is still due. */
+export const DEFAULT_CATCH_UP_DAYS = 3;
+/** The reminder `input.record` is due at `input.now`, or null (lifetime, outside every window). */
+export function getAccessReminder(input) {
+    const { record, accountCreatedAt, now, policy, catchUpDays } = input;
+    const entitlement = resolveEntitlement(record, now, policy);
+    if (entitlement.status !== "read_only") {
+        if (!entitlement.isEnding || entitlement.endsAt === null)
+            return null;
+        return { kind: entitlement.status === "trial" ? "trial-ending" : "paid-ending", endsAt: entitlement.endsAt };
+    }
+    if (getDayNumber(now, policy.timezone) - getDayNumber(entitlement.since, policy.timezone) > catchUpDays)
+        return null;
+    if (entitlement.reason === "paid_ended")
+        return { kind: "paid-ended", endsAt: entitlement.since };
+    return entitlement.since > accountCreatedAt ? { kind: "trial-ended", endsAt: entitlement.since } : null;
+}
+/**
+ * The delivery scope of a reminder in `mailing.deliveries`: one mail per account, kind and end, so
+ * a new end (an extended trial, a renewal, a refund) is a new window and the same end never mails twice.
+ */
+export function getAccessReminderScope(kind, userId, endsAt) {
+    return `billing.${kind}:${userId}:${String(endsAt.getTime())}`;
+}
+//# sourceMappingURL=reminder.js.map

package/dist/reminder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminder.js","sourceRoot":"","sources":["../src/reminder.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,kGAAkG;AAClG,kGAAkG;AAClG,qDAAqD;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EAAE,kBAAkB,EAA0B,MAAM,kBAAkB,CAAC;AAE9E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,CAAU,CAAC;AAG3G,4DAA4D;AAC5D,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AACrC,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAkBvC,mGAAmG;AACnG,MAAM,UAAU,iBAAiB,CAAC,KAA0B;IAC1D,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC;IACrE,MAAM,WAAW,GAAG,kBAAkB,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IAC5D,IAAI,WAAW,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QACvC,IAAI,CAAC,WAAW,CAAC,QAAQ,IAAI,WAAW,CAAC,MAAM,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QACtE,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,aAAa,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC;IAC/G,CAAC;IACD,IAAI,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,YAAY,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,WAAW;QAAE,OAAO,IAAI,CAAC;IACrH,IAAI,WAAW,CAAC,MAAM,KAAK,YAAY;QAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,CAAC,KAAK,EAAE,CAAC;IAClG,OAAO,WAAW,CAAC,KAAK,GAAG,gBAAgB,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1G,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAwB,EAAE,MAAc,EAAE,MAAY;IAC3F,OAAO,WAAW,IAAI,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;AACjE,CAAC"}