@tofound/billing 1.2.0 → 1.3.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,25 @@ 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.3.0 — 2026-10-28
8
+
9
+ Additive to 1.2: every 1.2 export is unchanged (the public-api declaration
10
+ snapshot only grows). No schema change. Without `display`, the served quote is
11
+ byte-identical to 1.2.0's.
12
+
13
+ To adopt: pin `@tofound/billing@1.3.0`.
14
+
15
+ - **Tax and renewal facts on the wire.** `QuoteWireOptions.display`
16
+ (`DisplayTerms`) adds `taxBehavior` (`inclusive` | `exclusive`),
17
+ `displayAmountMinor`, `displayCurrency` (ISO 4217) and renewal `interval`
18
+ (`month` | `year`) to `serializeQuote` and `serializePlanQuote`, after the
19
+ 1.2.0 keys. The host states them; the library computes no tax and changes no
20
+ price.
21
+ - **Offer wire.** New `serializeOffer(offer, { display? })` with types
22
+ `OfferWire`, `OfferWireOptions`, `DisplayTerms`, `TaxBehavior`,
23
+ `RenewalInterval`. A provider offer serves its own `interval`.
24
+ - **Docs:** API.md (display terms).
25
+
7
26
  ## 1.2.0 — 2026-10-25
8
27
 
9
28
  Additive to 1.1: every 1.1 export is unchanged (the public-api declaration
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
  products (2Novel first, the Lohi reader api last). Each host API embeds it on
5
5
  its own database; there is no billing service.
6
6
 
7
- 1.2 ships (the public API is frozen from 1.0.0 on; 1.1 and 1.2 only add):
7
+ 1.3 ships (the public API is frozen from 1.0.0 on; 1.1, 1.2 and 1.3 only add):
8
8
 
9
9
  - **The money core** (since 0.1): an idempotent, no-overdraft credit ledger
10
10
  behind store ports, memory and Drizzle/Postgres stores, a Drizzle schema
@@ -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.2.0 --exact # peer: drizzle-orm ^0.45 for /drizzle
26
+ bun add @tofound/billing@1.3.0 --exact # peer: drizzle-orm ^0.45 for /drizzle
27
27
  ```
28
28
 
29
29
  ```ts
@@ -6,4 +6,4 @@
6
6
  */
7
7
  export { createLegacyLedgerStore, LEGACY_KEY_PREFIX, type LegacyEntryRow, type LegacyLedgerCodec, type LegacyLedgerFields, type LegacyWalletDriver, } from './legacy-ledger.js';
8
8
  export { createAdminAdjustments, type AdjustmentInput, type AdjustmentOverdraft, type AdjustmentResult, type AdminAdjustments, type AdminAdjustmentsOptions, } from './adjustments.js';
9
- export { serializePlanQuote, serializeQuote, type FundingLineWire, type PlanQuoteWire, type QuoteLabeler, type QuoteWire, type QuoteWireOptions, } from './quote-wire.js';
9
+ export { serializeOffer, serializePlanQuote, serializeQuote, type DisplayTerms, type FundingLineWire, type OfferWire, type OfferWireOptions, type PlanQuoteWire, type QuoteLabeler, type QuoteWire, type QuoteWireOptions, type RenewalInterval, type TaxBehavior, } from './quote-wire.js';
@@ -6,4 +6,4 @@
6
6
  */
7
7
  export { createLegacyLedgerStore, LEGACY_KEY_PREFIX, } from './legacy-ledger.js';
8
8
  export { createAdminAdjustments, } from './adjustments.js';
9
- export { serializePlanQuote, serializeQuote, } from './quote-wire.js';
9
+ export { serializeOffer, serializePlanQuote, serializeQuote, } from './quote-wire.js';
@@ -1,3 +1,4 @@
1
+ import type { PlanOffer } from '../catalog/catalog.js';
1
2
  import type { FundingLine, Quote, QuoteReason, Settlement } from '../domain/types.js';
2
3
  import type { PlanQuoteKind } from '../terms/decide.js';
3
4
  import type { PlanQuote } from '../terms/plans.js';
@@ -16,7 +17,26 @@ export interface FundingLineWire {
16
17
  remainingAfter: number | null;
17
18
  label?: string;
18
19
  }
19
- export interface QuoteWire {
20
+ /** Whether the displayed price already contains tax (JP 総額表示, EU price indication) or tax is added at checkout. */
21
+ export type TaxBehavior = 'inclusive' | 'exclusive';
22
+ /** How often a subscription renews. */
23
+ export type RenewalInterval = 'month' | 'year';
24
+ /**
25
+ * Facts a host serves next to a price so a client can print the tax label, the
26
+ * amount the customer sees and the renewal cadence. The library computes none
27
+ * of them (no tax, no currency conversion); the host states what its provider
28
+ * charges. Every field is optional and left out of the wire when unset, so a
29
+ * 1.2.0 consumer decodes the wire unchanged.
30
+ */
31
+ export interface DisplayTerms {
32
+ taxBehavior?: TaxBehavior;
33
+ /** What the customer sees, in minor units of `displayCurrency`. Needs `displayCurrency`. */
34
+ displayAmountMinor?: number;
35
+ /** ISO 4217, three upper-case letters; wider than the ledger's `Currency`. Needs `displayAmountMinor`. */
36
+ displayCurrency?: string;
37
+ interval?: RenewalInterval;
38
+ }
39
+ export interface QuoteWire extends DisplayTerms {
20
40
  originalPrice: number;
21
41
  price: number;
22
42
  currency: string;
@@ -67,7 +87,28 @@ export interface QuoteWireOptions {
67
87
  * covered.
68
88
  */
69
89
  coveredSources?: readonly string[];
90
+ /** Tax, display amount and renewal facts to serve with the quote; see `DisplayTerms`. */
91
+ display?: DisplayTerms;
92
+ }
93
+ /** A plan offer a host lists: what it is, and the same display facts a quote carries. */
94
+ export interface OfferWire extends DisplayTerms {
95
+ source: PlanOffer['source'];
96
+ market?: string;
97
+ /** The provider's product ref; absent for a credit offer. */
98
+ productRef?: string;
99
+ /** Credit offers only: the length bought. */
100
+ months?: number;
101
+ }
102
+ /** `serializeOffer` options. Unlike a quote, an offer's interval defaults to the provider offer's own. */
103
+ export interface OfferWireOptions {
104
+ display?: DisplayTerms;
70
105
  }
71
106
  export declare function serializeQuote(quote: Quote, options?: QuoteWireOptions): QuoteWire;
72
107
  /** A plan quote (`createPlans().quote`): the purchase fields first, then the quote, then the period as ISO strings. */
73
108
  export declare function serializePlanQuote(quote: PlanQuote, options?: QuoteWireOptions): PlanQuoteWire;
109
+ /**
110
+ * A plan offer as served: identity first, then the display facts. A provider
111
+ * offer's `interval` is served unless the host overrides it; a credit offer has
112
+ * none (its `months` is the length). Nothing here is a price.
113
+ */
114
+ export declare function serializeOffer(offer: PlanOffer, options?: OfferWireOptions): OfferWire;
@@ -1,3 +1,33 @@
1
+ import { BillingError } from '../domain/errors.js';
2
+ import { assertMinor } from '../domain/money.js';
3
+ const TAX_BEHAVIORS = ['inclusive', 'exclusive'];
4
+ const INTERVALS = ['month', 'year'];
5
+ const ISO_CURRENCY = /^[A-Z]{3}$/;
6
+ /** Validates and orders the display facts; unset keys stay out, never `null`. */
7
+ function displayTerms(display) {
8
+ if (!display)
9
+ return {};
10
+ const { taxBehavior, displayAmountMinor, displayCurrency, interval } = display;
11
+ if (taxBehavior !== undefined && !TAX_BEHAVIORS.includes(taxBehavior)) {
12
+ throw new BillingError('invalid_input', `taxBehavior must be inclusive or exclusive, got ${String(taxBehavior)}`);
13
+ }
14
+ if (interval !== undefined && !INTERVALS.includes(interval)) {
15
+ throw new BillingError('invalid_input', `interval must be month or year, got ${String(interval)}`);
16
+ }
17
+ if ((displayAmountMinor === undefined) !== (displayCurrency === undefined)) {
18
+ throw new BillingError('invalid_input', 'displayAmountMinor and displayCurrency are served together');
19
+ }
20
+ if (displayAmountMinor !== undefined)
21
+ assertMinor(displayAmountMinor, 'displayAmountMinor');
22
+ if (displayCurrency !== undefined && !ISO_CURRENCY.test(displayCurrency)) {
23
+ throw new BillingError('invalid_input', `displayCurrency must be an ISO 4217 code, got ${String(displayCurrency)}`);
24
+ }
25
+ return {
26
+ ...(taxBehavior === undefined ? {} : { taxBehavior }),
27
+ ...(displayAmountMinor === undefined || displayCurrency === undefined ? {} : { displayAmountMinor, displayCurrency }),
28
+ ...(interval === undefined ? {} : { interval }),
29
+ };
30
+ }
1
31
  export function serializeQuote(quote, options = {}) {
2
32
  const labels = options.labels ?? {};
3
33
  const reasonLabel = labels.reason?.(quote.reason, quote) ?? quote.reason.label;
@@ -33,18 +63,39 @@ export function serializeQuote(quote, options = {}) {
33
63
  subscriptionCovered: quote.canSettle && quote.funding.length > 0 && quote.funding.every((l) => options.coveredSources.includes(l.source)),
34
64
  }
35
65
  : {}),
66
+ ...displayTerms(options.display),
36
67
  };
37
68
  }
38
69
  /** A plan quote (`createPlans().quote`): the purchase fields first, then the quote, then the period as ISO strings. */
39
70
  export function serializePlanQuote(quote, options = {}) {
71
+ const { display, ...quoteOptions } = options;
40
72
  return {
41
73
  kind: quote.kind,
42
74
  plan: quote.plan,
43
75
  months: quote.months,
44
76
  market: quote.market,
45
- ...serializeQuote(quote, options),
77
+ ...serializeQuote(quote, quoteOptions),
46
78
  periodStart: quote.periodStart?.toISOString() ?? null,
47
79
  periodEnd: quote.periodEnd?.toISOString() ?? null,
48
80
  scheduled: quote.scheduled,
81
+ // The display facts close the wire, after the period fields a 1.2.0 consumer reads.
82
+ ...displayTerms(display),
49
83
  };
50
84
  }
85
+ /**
86
+ * A plan offer as served: identity first, then the display facts. A provider
87
+ * offer's `interval` is served unless the host overrides it; a credit offer has
88
+ * none (its `months` is the length). Nothing here is a price.
89
+ */
90
+ export function serializeOffer(offer, options = {}) {
91
+ const own = offer.source === 'credit' ? undefined : offer.interval;
92
+ const terms = displayTerms({ ...options.display, interval: options.display?.interval ?? own });
93
+ return offer.source === 'credit'
94
+ ? { source: offer.source, ...(offer.market === undefined ? {} : { market: offer.market }), months: offer.months, ...terms }
95
+ : {
96
+ source: offer.source,
97
+ ...(offer.market === undefined ? {} : { market: offer.market }),
98
+ productRef: offer.productRef,
99
+ ...terms,
100
+ };
101
+ }
package/docs/API.md CHANGED
@@ -1,7 +1,7 @@
1
- # @tofound/billing — API (1.2)
1
+ # @tofound/billing — API (1.3)
2
2
 
3
3
  Part of the `billing.public-api` contract with `src/index.ts` and
4
- `src/domain/types.ts`. 0.x minors were additive; 1.1.0 and 1.2.0 are additive to 1.0.0. From 1.0.0 the API is
4
+ `src/domain/types.ts`. 0.x minors were additive; 1.1.0, 1.2.0 and 1.3.0 are additive to 1.0.0. From 1.0.0 the API is
5
5
  frozen: the declaration snapshot in `test/contract/public-api.test.ts` fails
6
6
  on any change to these exports, and removing or narrowing one is a major
7
7
  version. For task-oriented walkthroughs (packs, plans, failed renewals,
@@ -15,7 +15,7 @@ refunds, arming a provider) see [GUIDE.md](GUIDE.md).
15
15
  | `@tofound/billing/providers/polar` | `createPolarAdapter`, `resolvePolarEnvironment`, `respondPolar`, `redactPolarPayload`, `signPolarWebhook`, `PolarApiError`, `POLAR_WEBHOOK_*` header names and tolerance; types `PolarAdapter`, `PolarAdapterOptions`, `PolarCheckoutRequest`, `PolarKeyDerivation` |
16
16
  | `@tofound/billing/providers/apple` | `createAppleAdapter`, `respondApple`, `AppleApiError`, `APPLE_TRANSACTION_EVENT`, `APPLE_ROOT_CA_G3_PEM` / `_SHA256`, `APPLE_RECEIPT_SIGNING_OID`, `APPLE_WWDR_INTERMEDIATE_OID`; types `AppleAdapter`, `AppleAdapterOptions`, `AppleProduct`, `AppleServerApiCredentials`, `AppleTransactionProof` |
17
17
  | `@tofound/billing/providers/google` | `createGoogleAdapter`, `respondGoogle`, `GooglePlayApiError`, `GOOGLE_RTDN_EVENT`, `GOOGLE_PURCHASE_EVENT`, `GOOGLE_VOIDED_EVENT`; types `GoogleAdapter`, `GoogleAdapterOptions`, `GoogleProduct`, `GooglePurchaseProof`, `PubSubAuth`, `ServiceAccount` |
18
- | `@tofound/billing/hostkit` | `createLegacyLedgerStore`, `LEGACY_KEY_PREFIX`, `createAdminAdjustments`, `serializeQuote`, `serializePlanQuote`; types `LegacyWalletDriver`, `LegacyEntryRow`, `LegacyLedgerFields`, `LegacyLedgerCodec`, `AdjustmentInput`, `AdjustmentResult`, `AdjustmentOverdraft`, `AdminAdjustments`, `AdminAdjustmentsOptions`, `QuoteWire`, `PlanQuoteWire`, `FundingLineWire`, `QuoteLabeler`, `QuoteWireOptions` |
18
+ | `@tofound/billing/hostkit` | `createLegacyLedgerStore`, `LEGACY_KEY_PREFIX`, `createAdminAdjustments`, `serializeQuote`, `serializePlanQuote`, `serializeOffer`; types `LegacyWalletDriver`, `LegacyEntryRow`, `LegacyLedgerFields`, `LegacyLedgerCodec`, `AdjustmentInput`, `AdjustmentResult`, `AdjustmentOverdraft`, `AdminAdjustments`, `AdminAdjustmentsOptions`, `QuoteWire`, `PlanQuoteWire`, `FundingLineWire`, `QuoteLabeler`, `QuoteWireOptions`, `OfferWire`, `OfferWireOptions`, `DisplayTerms`, `TaxBehavior`, `RenewalInterval` |
19
19
  | `@tofound/billing/testing` | `ledgerConformanceCases`, `assertLedgerInvariants`, `assertQuoteMatchesSettlement`, `ingestConformanceCases`, `termConformanceCases`, memory stores |
20
20
 
21
21
  The library reads no env, logs nothing and has no runtime dependencies. Every
@@ -693,3 +693,18 @@ quote:
693
693
 
694
694
  **`serializePlanQuote`** puts `kind, plan, months, market` first and
695
695
  `periodStart, periodEnd` (ISO strings or `null`) and `scheduled` last.
696
+
697
+ **Display terms (1.3.0).** `serializeQuote`/`serializePlanQuote` take
698
+ `display?: DisplayTerms` and `serializeOffer(offer, { display? })` serves a
699
+ catalog offer (`source, market?, productRef?` or `months`) with the same
700
+ facts:
701
+ - `taxBehavior` (`'inclusive' | 'exclusive'`), `displayAmountMinor` and
702
+ `displayCurrency` (ISO 4217; served together) and `interval`
703
+ (`'month' | 'year'`; a provider offer's own interval by default);
704
+ - the host states them: the library computes no tax and converts nothing, and
705
+ `price` / `originalPrice` are untouched;
706
+ - unset facts are left out, never `null`, and they come last on the wire
707
+ (after `scheduled` on a plan quote), so without `display` the wire is
708
+ exactly 1.2.0's;
709
+ - a bad value throws `invalid_input` (`invalid_amount` for a negative or
710
+ non-integer amount).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tofound/billing",
3
- "version": "1.2.0",
3
+ "version": "1.3.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",