@tofound/billing 1.4.0 → 1.5.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 CHANGED
@@ -4,6 +4,29 @@ All notable changes to `@tofound/billing`. Versions follow semver; 0.x minors
4
4
  were additive. From 1.0.0 the public API is frozen: removing or narrowing
5
5
  anything in the declaration snapshot is a major version.
6
6
 
7
+ ## 1.5.0 — 2026-11-06
8
+
9
+ Additive to 1.4: every 1.4 export is unchanged (the public-api declaration
10
+ snapshot only grows). No schema change (`billing_terms.source` is already a
11
+ `varchar(16)`). Terms and offers of the existing sources behave exactly as in
12
+ 1.4.0.
13
+
14
+ To adopt: pin `@tofound/billing@1.5.0`.
15
+
16
+ - **SePay prepay terms.** `TermSource` gains `'sepay'`: a manual prepay the
17
+ host opens when a transfer settles. It never auto-renews; `entitledUntil`
18
+ keeps it entitled for `policies.graceDays` after `currentPeriodEnd` so a
19
+ late re-payment extends it without a gap. As a non-credit term it carries
20
+ the plan's `includedCredits`, and the credit renewal job skips it. A host
21
+ with an exhaustive `switch` over `TermSource` / `Term.source` /
22
+ `Entitlement.source` adds a `'sepay'` arm when it adopts 1.5.0.
23
+ - **SePay prepay offers.** `ProviderOffer.source` gains `'sepay'` and an
24
+ optional `months`. A `sepay` offer needs `market`, `months` and `price` (for
25
+ the whole `months`), takes no `interval`, and is unique per market and
26
+ months. New catalog lookups `prepayOffer(plan, market, months)` and
27
+ `prepayOffers(plan, market)`.
28
+ - **Docs:** GUIDE §4 (SePay prepay) and §5 (failed renewal per source).
29
+
7
30
  ## 1.4.0 — 2026-10-29
8
31
 
9
32
  Additive to 1.3: every 1.3 export is unchanged (the public-api declaration
package/README.md CHANGED
@@ -23,7 +23,7 @@ its own database; there is no billing service.
23
23
  (`@tofound/billing/providers/google`) adapters.
24
24
 
25
25
  ```sh
26
- bun add @tofound/billing@1.4.0 --exact # peer: drizzle-orm ^0.45 for /drizzle
26
+ bun add @tofound/billing@1.5.0 --exact # peer: drizzle-orm ^0.45 for /drizzle
27
27
  ```
28
28
 
29
29
  ```ts
@@ -12,15 +12,21 @@ export interface CreditOffer {
12
12
  /** Credit minor units for the whole `months`. */
13
13
  credits: number;
14
14
  }
15
- /** A provider-billed offer; `productRef` maps to the provider's product id in host config. */
15
+ /**
16
+ * A provider-billed offer; `productRef` maps to the provider's product id in host config.
17
+ * A `sepay` offer is a manual prepay: `market`, `months` and `price` (the whole
18
+ * `months`) are required, one per market and months, and it never auto-renews.
19
+ */
16
20
  export interface ProviderOffer {
17
- source: 'polar' | 'apple' | 'google';
21
+ source: 'sepay' | 'polar' | 'apple' | 'google';
18
22
  productRef: string;
19
23
  market?: string;
20
24
  interval?: 'month' | 'year';
21
25
  price?: Money;
22
26
  /** Google base plan id. */
23
27
  basePlan?: string;
28
+ /** `sepay` only: catalog months the prepay buys. */
29
+ months?: number;
24
30
  }
25
31
  export type PlanOffer = CreditOffer | ProviderOffer;
26
32
  export interface PlanSpec {
@@ -106,6 +112,10 @@ export interface Catalog {
106
112
  creditOffer(plan: string, market: string, months: number): CreditOffer | undefined;
107
113
  /** Credit offers of a plan in a market, fewest months first. */
108
114
  creditOffers(plan: string, market: string): CreditOffer[];
115
+ /** The `sepay` prepay offer of a plan for `months` in a market. */
116
+ prepayOffer(plan: string, market: string, months: number): ProviderOffer | undefined;
117
+ /** `sepay` prepay offers of a plan in a market, fewest months first. */
118
+ prepayOffers(plan: string, market: string): ProviderOffer[];
109
119
  pack(key: string): CreditPack | undefined;
110
120
  packsFor(market: string, provider?: PackProvider): CreditPack[];
111
121
  /** The plan offer or credit pack a provider product ref names. */
@@ -105,6 +105,7 @@ export function defineCatalog(spec) {
105
105
  offers,
106
106
  };
107
107
  const creditMonths = new Set();
108
+ const prepayMonths = new Set();
108
109
  for (const o of p.offers ?? []) {
109
110
  const what = `plan ${p.key} ${o.source} offer`;
110
111
  if (o.source === 'credit') {
@@ -119,6 +120,24 @@ export function defineCatalog(spec) {
119
120
  creditMonths.add(slot);
120
121
  offers.push(Object.freeze({ source: 'credit', market: o.market, months: o.months, credits: o.credits }));
121
122
  }
123
+ else if (o.source === 'sepay') {
124
+ checkMarket(o.market, what);
125
+ if (o.market === undefined)
126
+ fail(`${what}: market is required`);
127
+ safeInt(o.months, `${what} months`, 1);
128
+ if (!o.price)
129
+ fail(`${what}: price is required`);
130
+ checkMoney(o.price, o.market, what);
131
+ if (o.interval !== undefined)
132
+ fail(`${what}: a prepay has months, not an interval`);
133
+ const slot = `${o.market}:${o.months}`;
134
+ if (prepayMonths.has(slot))
135
+ fail(`${what}: ${o.months} months in ${o.market} is offered twice`);
136
+ prepayMonths.add(slot);
137
+ const offer = Object.freeze({ ...o, price: Object.freeze({ ...o.price }) });
138
+ claimRef(o.productRef, { kind: 'plan', plan, offer }, what);
139
+ offers.push(offer);
140
+ }
122
141
  else if (o.source === 'polar' || o.source === 'apple' || o.source === 'google') {
123
142
  checkMarket(o.market, what);
124
143
  checkMoney(o.price, o.market, what);
@@ -175,6 +194,9 @@ export function defineCatalog(spec) {
175
194
  const creditOffers = (plan, market) => (byKey.get(plan)?.offers ?? [])
176
195
  .filter((o) => o.source === 'credit' && o.market === market)
177
196
  .sort((a, b) => a.months - b.months);
197
+ const prepayOffers = (plan, market) => (byKey.get(plan)?.offers ?? [])
198
+ .filter((o) => o.source === 'sepay' && o.market === market)
199
+ .sort((a, b) => (a.months ?? 0) - (b.months ?? 0));
178
200
  return Object.freeze({
179
201
  version: spec.version,
180
202
  creditUnit: Object.freeze({ code: unit.code, exponent: unit.exponent }),
@@ -194,6 +216,8 @@ export function defineCatalog(spec) {
194
216
  market: (key) => markets.get(key),
195
217
  creditOffer: (plan, market, months) => creditOffers(plan, market).find((o) => o.months === months),
196
218
  creditOffers,
219
+ prepayOffer: (plan, market, months) => prepayOffers(plan, market).find((o) => o.months === months),
220
+ prepayOffers,
197
221
  pack: (key) => packs.find((p) => p.key === key),
198
222
  packsFor: (market, provider) => packs.filter((p) => p.market === market && (!provider || p.provider === provider)),
199
223
  offerByProductRef: (productRef) => productRefs.get(productRef),
@@ -59,7 +59,9 @@ export interface ResolveOptions {
59
59
  *
60
60
  * - `active` before its period end. An auto-renewing term past its end is
61
61
  * still entitled for `graceDays` while the renewal (job or provider
62
- * webhook) catches up — the renewal itself decides past_due.
62
+ * webhook) catches up — the renewal itself decides past_due. A `sepay`
63
+ * prepay never auto-renews but keeps the same `graceDays`, so a user who
64
+ * re-pays a day late is not cut off.
63
65
  * - `grace` until `graceUntil` (the period end when the provider sent none).
64
66
  * - `past_due` only while `graceUntil` is ahead (a credit term's 3-day grace,
65
67
  * AC15); a provider `past_due` without one is not entitled (§4.6).
@@ -4,7 +4,9 @@ import { addDays } from '../terms/rules.js';
4
4
  *
5
5
  * - `active` before its period end. An auto-renewing term past its end is
6
6
  * still entitled for `graceDays` while the renewal (job or provider
7
- * webhook) catches up — the renewal itself decides past_due.
7
+ * webhook) catches up — the renewal itself decides past_due. A `sepay`
8
+ * prepay never auto-renews but keeps the same `graceDays`, so a user who
9
+ * re-pays a day late is not cut off.
8
10
  * - `grace` until `graceUntil` (the period end when the provider sent none).
9
11
  * - `past_due` only while `graceUntil` is ahead (a credit term's 3-day grace,
10
12
  * AC15); a provider `past_due` without one is not entitled (§4.6).
@@ -20,7 +22,8 @@ export function entitledUntil(term, now, graceDays) {
20
22
  return null;
21
23
  if (at < term.currentPeriodEnd.getTime())
22
24
  return term.currentPeriodEnd;
23
- return term.autoRenew && !term.cancelAtPeriodEnd ? before(addDays(term.currentPeriodEnd, graceDays)) : null;
25
+ // A renewing term, or a sepay prepay the user re-pays by hand, keeps `graceDays` past its end.
26
+ return (term.autoRenew && !term.cancelAtPeriodEnd) || term.source === 'sepay' ? before(addDays(term.currentPeriodEnd, graceDays)) : null;
24
27
  }
25
28
  case 'grace':
26
29
  return before(term.graceUntil ?? term.currentPeriodEnd);
@@ -1,11 +1,14 @@
1
1
  /**
2
- * Subscription terms (design §4.6): one shape for the four sources. Credit
2
+ * Subscription terms (design §4.6): one shape for every source. Credit
3
3
  * terms are written only by the plans and renewal services; provider terms
4
- * only from `subscription.snapshot` events, under a watermark.
4
+ * only from `subscription.snapshot` events, under a watermark. A `sepay` term
5
+ * is a manual prepay (SePay has no charge-on-file): the host opens it when the
6
+ * transfer settles; it never auto-renews and is entitled for `graceDays` after
7
+ * its end so a late re-payment extends it without a gap.
5
8
  */
6
9
  import type { AccountId } from '../domain/types.js';
7
10
  import type { ProviderEnvironment } from '../providers/port.js';
8
- export type TermSource = 'credit' | 'polar' | 'apple' | 'google';
11
+ export type TermSource = 'credit' | 'sepay' | 'polar' | 'apple' | 'google';
9
12
  /**
10
13
  * - `scheduled`: a credit term that starts at `startsAt` (S3b), charged then.
11
14
  * - `active`: entitled until the period end.
package/docs/GUIDE.md CHANGED
@@ -169,6 +169,17 @@ default handlers apply through it and report the credit they post.
169
169
  5. Give the buyer the provider's portal for card and cancel:
170
170
  `polar.createPortalSession({ kind: 'account_id', value: accountId }, returnUrl)`.
171
171
 
172
+ **A SePay prepay** (no charge-on-file) is a `sepay` offer
173
+ `{ source: 'sepay', productRef, market, months, price }` — `price` is the whole
174
+ `months`, one offer per market and months; look it up with
175
+ `catalog.prepayOffer(plan, market, months)`. There is no snapshot: when the
176
+ transfer settles, the host inserts a `source: 'sepay'` term itself
177
+ (`externalId` = its order id, so a replayed settlement hits the
178
+ `(source, environment, externalId)` unique key and opens nothing), with
179
+ `autoRenew: false`. It is entitled until `currentPeriodEnd + graceDays`; a
180
+ re-payment extends it from `max(now, currentPeriodEnd)`, and the host
181
+ expires it after the grace. It carries the plan's `includedCredits`.
182
+
172
183
  ## 5. Handle a failed renewal, per source
173
184
 
174
185
  | Source | What fails | What the library does | What the host does |
@@ -176,6 +187,7 @@ default handlers apply through it and report the credit they post.
176
187
  | **Credit renewal** | Balance below the live price at `periodEnd − renewalLeadSec` | An early failure emits `renewal_failed` and leaves the term `active`. At the period end the term becomes `past_due` with `graceUntil = periodEnd + graceDays`, still entitled. After the grace it is `expired`. | Show the shortfall from the `renewal_failed` event (`required`, `balance`, `shortfall`). A top-up fires `afterCredited`, which calls `retryPastDue`; the renewal timer retries too. |
177
188
  | **Polar subscription** | The card is declined; Polar retries | The snapshot goes `past_due` and the term gets a grace window. `revoked`, or `canceled` once ended, ends access. Snapshots are ordered by Polar's `modified_at`, so an old one cannot undo a new one. | Show "update your card" with the portal link. A card fix arrives as an `active` snapshot; nothing else to do. |
178
189
  | **Apple** | Billing retry or grace period (App Store) | Auto-renewable notifications become snapshots with `past_due` / `grace`. One-time (consumable) purchases are keyed by transaction; a refund reverses once. | Treat Apple's own retry and grace as the source of truth; do not charge credits for an Apple term. Selling Apple subscriptions is the host's decision; the adapter handles the notifications. |
190
+ | **SePay prepay** | Nothing is charged: the period simply ends | Entitled for `graceDays` after `currentPeriodEnd`, never renewed (`renewal.auto` is `false`); the renewal job skips it. | Nudge before the end with a checkout link; a paid re-checkout extends the term; expire it after the grace. |
179
191
  | **Any webhook** | The handler throws | The row is `failed`, answered 5xx so the provider redelivers, retried by `sweep` with backoff, then `dead` with a `billing.alert`. | Alert on `billing.alert`; fix the cause and `ingest.replay(provider, eventId)`. |
180
192
 
181
193
  A failed **pack** payment creates no order and no credit; the session simply
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tofound/billing",
3
- "version": "1.4.0",
3
+ "version": "1.5.0",
4
4
  "description": "Shared subscription and credit library by 2found: credit ledger, quote/charge waterfall, Drizzle schema factory.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",