@tofound/billing 0.0.0-stage → 0.2.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 +122 -0
- package/LICENSE +3 -0
- package/README.md +79 -2
- package/dist/catalog/catalog.d.ts +115 -0
- package/dist/catalog/catalog.js +201 -0
- package/dist/domain/errors.d.ts +14 -0
- package/dist/domain/errors.js +21 -0
- package/dist/domain/money.d.ts +21 -0
- package/dist/domain/money.js +77 -0
- package/dist/domain/types.d.ts +167 -0
- package/dist/domain/types.js +18 -0
- package/dist/drizzle/index.d.ts +5 -0
- package/dist/drizzle/index.js +5 -0
- package/dist/drizzle/schema-factory.d.ts +586 -0
- package/dist/drizzle/schema-factory.js +206 -0
- package/dist/drizzle/store.d.ts +20 -0
- package/dist/drizzle/store.js +124 -0
- package/dist/entitlement/resolve.d.ts +76 -0
- package/dist/entitlement/resolve.js +122 -0
- package/dist/inbox/apply.d.ts +48 -0
- package/dist/inbox/apply.js +299 -0
- package/dist/inbox/conformance.d.ts +20 -0
- package/dist/inbox/conformance.js +254 -0
- package/dist/inbox/drizzle.d.ts +14 -0
- package/dist/inbox/drizzle.js +203 -0
- package/dist/inbox/ingest.d.ts +108 -0
- package/dist/inbox/ingest.js +404 -0
- package/dist/inbox/memory.d.ts +13 -0
- package/dist/inbox/memory.js +172 -0
- package/dist/inbox/ports.d.ts +150 -0
- package/dist/inbox/ports.js +1 -0
- package/dist/inbox/redact.d.ts +2 -0
- package/dist/inbox/redact.js +47 -0
- package/dist/inbox/schema.d.ts +1158 -0
- package/dist/inbox/schema.js +90 -0
- package/dist/inbox/watermark.d.ts +13 -0
- package/dist/inbox/watermark.js +6 -0
- package/dist/index.d.ts +30 -0
- package/dist/index.js +27 -0
- package/dist/ledger/ledger.d.ts +47 -0
- package/dist/ledger/ledger.js +224 -0
- package/dist/ports/index.d.ts +2 -0
- package/dist/ports/index.js +1 -0
- package/dist/ports/ledger-store.d.ts +53 -0
- package/dist/ports/ledger-store.js +1 -0
- package/dist/ports/runtime.d.ts +9 -0
- package/dist/ports/runtime.js +1 -0
- package/dist/providers/polar/events.d.ts +17 -0
- package/dist/providers/polar/events.js +213 -0
- package/dist/providers/polar/index.d.ts +50 -0
- package/dist/providers/polar/index.js +271 -0
- package/dist/providers/polar/signature.d.ts +23 -0
- package/dist/providers/polar/signature.js +52 -0
- package/dist/providers/port.d.ts +207 -0
- package/dist/providers/port.js +30 -0
- package/dist/providers/sepay/index.d.ts +34 -0
- package/dist/providers/sepay/index.js +241 -0
- package/dist/providers/sepay/order.d.ts +32 -0
- package/dist/providers/sepay/order.js +69 -0
- package/dist/providers/sepay/signature.d.ts +8 -0
- package/dist/providers/sepay/signature.js +51 -0
- package/dist/quote/conformance.d.ts +16 -0
- package/dist/quote/conformance.js +39 -0
- package/dist/quote/index.d.ts +3 -0
- package/dist/quote/index.js +3 -0
- package/dist/quote/steps.d.ts +54 -0
- package/dist/quote/steps.js +103 -0
- package/dist/quote/waterfall.d.ts +98 -0
- package/dist/quote/waterfall.js +82 -0
- package/dist/renewal/renewal.d.ts +69 -0
- package/dist/renewal/renewal.js +198 -0
- package/dist/stores/conformance.d.ts +22 -0
- package/dist/stores/conformance.js +269 -0
- package/dist/stores/memory.d.ts +19 -0
- package/dist/stores/memory.js +137 -0
- package/dist/stores/testing.d.ts +13 -0
- package/dist/stores/testing.js +13 -0
- package/dist/terms/conformance.d.ts +17 -0
- package/dist/terms/conformance.js +198 -0
- package/dist/terms/decide.d.ts +97 -0
- package/dist/terms/decide.js +176 -0
- package/dist/terms/drizzle.d.ts +12 -0
- package/dist/terms/drizzle.js +131 -0
- package/dist/terms/memory.d.ts +23 -0
- package/dist/terms/memory.js +126 -0
- package/dist/terms/plans.d.ts +85 -0
- package/dist/terms/plans.js +331 -0
- package/dist/terms/ports.d.ts +55 -0
- package/dist/terms/ports.js +1 -0
- package/dist/terms/rules.d.ts +11 -0
- package/dist/terms/rules.js +36 -0
- package/dist/terms/schema.d.ts +711 -0
- package/dist/terms/schema.js +70 -0
- package/dist/terms/snapshot.d.ts +20 -0
- package/dist/terms/snapshot.js +134 -0
- package/dist/terms/types.d.ts +85 -0
- package/dist/terms/types.js +4 -0
- package/docs/API.md +417 -0
- package/docs/SCHEMA.md +163 -0
- package/package.json +80 -4
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Public domain types of `@tofound/billing` — part of the `billing.public-api`
|
|
3
|
+
* contract. Additive changes only within 0.x minors; every amount is an
|
|
4
|
+
* integer in minor units (no float math anywhere in the library).
|
|
5
|
+
*/
|
|
6
|
+
/** Fiat currencies a market prices in. */
|
|
7
|
+
export type Currency = 'VND' | 'USD';
|
|
8
|
+
/** A fiat amount in the currency's minor unit (VND exponent 0, USD 2). */
|
|
9
|
+
export interface Money {
|
|
10
|
+
currency: Currency;
|
|
11
|
+
amountMinor: number;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* A host's store of value. Balances and ledger deltas are integers in
|
|
15
|
+
* `10^-exponent` of one unit: Lohi `{code:'LT', exponent:0}`, 2Novel
|
|
16
|
+
* `{code:'credit', exponent:2}` (1 minor unit = 1 đ at 100 đ = 1 credit).
|
|
17
|
+
*/
|
|
18
|
+
export interface CreditUnit {
|
|
19
|
+
code: string;
|
|
20
|
+
exponent: number;
|
|
21
|
+
}
|
|
22
|
+
/** Rounding of a non-integral result; grants and refunds favour the customer. */
|
|
23
|
+
export type RoundingMode = 'floor' | 'ceil' | 'half_up';
|
|
24
|
+
/** The host's subject id: a 2Novel workspace id or a Lohi user id. */
|
|
25
|
+
export type AccountId = string;
|
|
26
|
+
export declare const ENTRY_KINDS: readonly ["topup", "grant", "spend", "refund", "plan_purchase", "plan_renewal", "plan_refund", "reversal", "conversion", "resync", "adjustment"];
|
|
27
|
+
export type EntryKind = (typeof ENTRY_KINDS)[number];
|
|
28
|
+
/** JSON-serialisable metadata carried on an entry. */
|
|
29
|
+
export type EntryMeta = Record<string, unknown>;
|
|
30
|
+
/**
|
|
31
|
+
* One append-only ledger row. Invariants (I1–I6): `balanceAfter` =
|
|
32
|
+
* previous `balanceAfter` + `delta`, `seq` contiguous per account,
|
|
33
|
+
* `balanceAfter` ≥ 0, `idempotencyKey` globally unique, entries never change.
|
|
34
|
+
*/
|
|
35
|
+
export interface LedgerEntry {
|
|
36
|
+
id: string;
|
|
37
|
+
accountId: AccountId;
|
|
38
|
+
seq: number;
|
|
39
|
+
/** Signed, in credit minor units. */
|
|
40
|
+
delta: number;
|
|
41
|
+
balanceAfter: number;
|
|
42
|
+
kind: EntryKind;
|
|
43
|
+
/** Host label kept for analytics, e.g. Lohi `tts_pro`. */
|
|
44
|
+
reason: string | null;
|
|
45
|
+
idempotencyKey: string;
|
|
46
|
+
sourceType: string | null;
|
|
47
|
+
sourceId: string | null;
|
|
48
|
+
/** The entry this one reverses (kind `reversal`). */
|
|
49
|
+
reversesId: string | null;
|
|
50
|
+
meta: EntryMeta | null;
|
|
51
|
+
createdAt: Date;
|
|
52
|
+
}
|
|
53
|
+
/** The materialized balance of one account. */
|
|
54
|
+
export interface AccountState {
|
|
55
|
+
accountId: AccountId;
|
|
56
|
+
balance: number;
|
|
57
|
+
/** Seq of the last entry; 0 for an account with no entries. */
|
|
58
|
+
seq: number;
|
|
59
|
+
}
|
|
60
|
+
/** Where a posting came from (a job, a checkout, an admin request …). */
|
|
61
|
+
export interface EntrySource {
|
|
62
|
+
type: string;
|
|
63
|
+
id: string;
|
|
64
|
+
}
|
|
65
|
+
/** A credit or debit request. `amount` is a positive safe integer. */
|
|
66
|
+
export interface PostInput {
|
|
67
|
+
accountId: AccountId;
|
|
68
|
+
kind: EntryKind;
|
|
69
|
+
amount: number;
|
|
70
|
+
idempotencyKey: string;
|
|
71
|
+
reason?: string | null;
|
|
72
|
+
source?: EntrySource | null;
|
|
73
|
+
meta?: EntryMeta | null;
|
|
74
|
+
}
|
|
75
|
+
/** A partial or full counter-entry for an existing entry. */
|
|
76
|
+
export interface ReverseInput {
|
|
77
|
+
entryId: string;
|
|
78
|
+
idempotencyKey: string;
|
|
79
|
+
/** Defaults to |original delta|; at most that. */
|
|
80
|
+
amount?: number;
|
|
81
|
+
reason?: string | null;
|
|
82
|
+
meta?: EntryMeta | null;
|
|
83
|
+
}
|
|
84
|
+
/** Domain events a host maps onto its own bus (design §13). */
|
|
85
|
+
export type BillingEvent = {
|
|
86
|
+
type: 'credited';
|
|
87
|
+
accountId: AccountId;
|
|
88
|
+
entry: LedgerEntry;
|
|
89
|
+
} | {
|
|
90
|
+
type: 'debited';
|
|
91
|
+
accountId: AccountId;
|
|
92
|
+
entry: LedgerEntry;
|
|
93
|
+
};
|
|
94
|
+
export interface PostResult {
|
|
95
|
+
entry: LedgerEntry;
|
|
96
|
+
/** True when the idempotency key had already been posted with the same intent. */
|
|
97
|
+
replayed: boolean;
|
|
98
|
+
/**
|
|
99
|
+
* Events of this posting (empty on replay). When the ledger owns the
|
|
100
|
+
* transaction they are also sent to the configured sink after commit;
|
|
101
|
+
* under `ledger.in(tx)` the host emits them after its own commit.
|
|
102
|
+
*/
|
|
103
|
+
events: BillingEvent[];
|
|
104
|
+
}
|
|
105
|
+
export interface DebitUpToResult extends PostResult {
|
|
106
|
+
requested: number;
|
|
107
|
+
/** `requested − posted`; recorded on the entry as `meta.debitUpTo`. */
|
|
108
|
+
shortfall: number;
|
|
109
|
+
}
|
|
110
|
+
export interface EntryPage {
|
|
111
|
+
entries: LedgerEntry[];
|
|
112
|
+
/** Pass as `beforeSeq` for the next (older) page; null when exhausted. */
|
|
113
|
+
nextBeforeSeq: number | null;
|
|
114
|
+
}
|
|
115
|
+
export type BillingErrorCode = 'insufficient_credits' | 'idempotency_mismatch' | 'invalid_amount' | 'invalid_input' | 'entry_not_found' | 'reversal_exceeds_original' | 'already_reversed' | 'balance_overflow' | 'invalid_catalog' | 'plan_not_found' | 'offer_not_found' | 'term_not_found'
|
|
116
|
+
/** A plan purchase the quote refuses (`details.reason`, e.g. `covered_by_subscription`). */
|
|
117
|
+
| 'plan_blocked';
|
|
118
|
+
/** Details carried by `insufficient_credits`. */
|
|
119
|
+
export interface InsufficientCredits {
|
|
120
|
+
balance: number;
|
|
121
|
+
required: number;
|
|
122
|
+
shortfall: number;
|
|
123
|
+
}
|
|
124
|
+
/** How a settlement ends. `blocked` means it cannot, and why is in `reason`. */
|
|
125
|
+
export type Settlement = 'free' | 'quota' | 'wallet' | 'blocked';
|
|
126
|
+
/** A code the host labels; the library never composes user-facing copy. */
|
|
127
|
+
export interface QuoteReason {
|
|
128
|
+
code: string;
|
|
129
|
+
label?: string;
|
|
130
|
+
detail?: string;
|
|
131
|
+
}
|
|
132
|
+
/** One line of the settlement plan, in waterfall order. */
|
|
133
|
+
export interface FundingLine {
|
|
134
|
+
/** Step source, e.g. `byok`, `subscription_quota`, `wallet`. */
|
|
135
|
+
source: string;
|
|
136
|
+
/** What `amount` is denominated in: the credit unit code for money lines. */
|
|
137
|
+
unit: string;
|
|
138
|
+
amount: number;
|
|
139
|
+
/** Pool size before/after this line; `null` = unmetered. */
|
|
140
|
+
remainingBefore: number | null;
|
|
141
|
+
remainingAfter: number | null;
|
|
142
|
+
label?: string;
|
|
143
|
+
}
|
|
144
|
+
export interface Quote {
|
|
145
|
+
/** List price in credit minor units, before anything is applied. */
|
|
146
|
+
originalPrice: number;
|
|
147
|
+
/** What the wallet will actually be debited. */
|
|
148
|
+
price: number;
|
|
149
|
+
/** The credit unit code. */
|
|
150
|
+
currency: string;
|
|
151
|
+
reason: QuoteReason;
|
|
152
|
+
/** The plan in walk order; `funding[0]` is the primary source. */
|
|
153
|
+
funding: FundingLine[];
|
|
154
|
+
settlement: Settlement;
|
|
155
|
+
canSettle: boolean;
|
|
156
|
+
/** Credit minor units short; present only when `settlement === 'blocked'` for money. */
|
|
157
|
+
shortfall?: number;
|
|
158
|
+
/** `null` when the state has no account (guest). */
|
|
159
|
+
balance: number | null;
|
|
160
|
+
/** The plan that would remove this charge, when one would. */
|
|
161
|
+
upsell?: {
|
|
162
|
+
plan: string;
|
|
163
|
+
label?: string;
|
|
164
|
+
};
|
|
165
|
+
/** A quote is a forecast; settle re-derives everything. */
|
|
166
|
+
expiresInSec: number;
|
|
167
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Public domain types of `@tofound/billing` — part of the `billing.public-api`
|
|
3
|
+
* contract. Additive changes only within 0.x minors; every amount is an
|
|
4
|
+
* integer in minor units (no float math anywhere in the library).
|
|
5
|
+
*/
|
|
6
|
+
export const ENTRY_KINDS = [
|
|
7
|
+
'topup',
|
|
8
|
+
'grant',
|
|
9
|
+
'spend',
|
|
10
|
+
'refund',
|
|
11
|
+
'plan_purchase',
|
|
12
|
+
'plan_renewal',
|
|
13
|
+
'plan_refund',
|
|
14
|
+
'reversal',
|
|
15
|
+
'conversion',
|
|
16
|
+
'resync',
|
|
17
|
+
'adjustment',
|
|
18
|
+
];
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export { billingTableBuilder, checkAdditiveDdl, createBillingTables, DEFAULT_PREFIX, type BillingSchemaConfig, type BillingTables, type CheckAdditiveDdlOptions, type DdlRule, type DdlViolation, } from './schema-factory.js';
|
|
2
|
+
export { createDrizzleLedgerStore, type AnyPgDatabase, type AnyPgTransaction, type DrizzleLedgerStoreOptions, } from './store.js';
|
|
3
|
+
export { createDrizzleIngestStore, createIngestTables, ingestTableNames, type DrizzleIngestStoreOptions, type IngestTables, } from '../inbox/drizzle.js';
|
|
4
|
+
export { createTermTables, termTableNames, type TermTables } from '../terms/schema.js';
|
|
5
|
+
export { createDrizzleTermStore, type DrizzleTermStoreOptions } from '../terms/drizzle.js';
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export { billingTableBuilder, checkAdditiveDdl, createBillingTables, DEFAULT_PREFIX, } from './schema-factory.js';
|
|
2
|
+
export { createDrizzleLedgerStore, } from './store.js';
|
|
3
|
+
export { createDrizzleIngestStore, createIngestTables, ingestTableNames, } from '../inbox/drizzle.js';
|
|
4
|
+
export { createTermTables, termTableNames } from '../terms/schema.js';
|
|
5
|
+
export { createDrizzleTermStore } from '../terms/drizzle.js';
|