@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.
Files changed (100) hide show
  1. package/CHANGELOG.md +122 -0
  2. package/LICENSE +3 -0
  3. package/README.md +79 -2
  4. package/dist/catalog/catalog.d.ts +115 -0
  5. package/dist/catalog/catalog.js +201 -0
  6. package/dist/domain/errors.d.ts +14 -0
  7. package/dist/domain/errors.js +21 -0
  8. package/dist/domain/money.d.ts +21 -0
  9. package/dist/domain/money.js +77 -0
  10. package/dist/domain/types.d.ts +167 -0
  11. package/dist/domain/types.js +18 -0
  12. package/dist/drizzle/index.d.ts +5 -0
  13. package/dist/drizzle/index.js +5 -0
  14. package/dist/drizzle/schema-factory.d.ts +586 -0
  15. package/dist/drizzle/schema-factory.js +206 -0
  16. package/dist/drizzle/store.d.ts +20 -0
  17. package/dist/drizzle/store.js +124 -0
  18. package/dist/entitlement/resolve.d.ts +76 -0
  19. package/dist/entitlement/resolve.js +122 -0
  20. package/dist/inbox/apply.d.ts +48 -0
  21. package/dist/inbox/apply.js +299 -0
  22. package/dist/inbox/conformance.d.ts +20 -0
  23. package/dist/inbox/conformance.js +254 -0
  24. package/dist/inbox/drizzle.d.ts +14 -0
  25. package/dist/inbox/drizzle.js +203 -0
  26. package/dist/inbox/ingest.d.ts +108 -0
  27. package/dist/inbox/ingest.js +404 -0
  28. package/dist/inbox/memory.d.ts +13 -0
  29. package/dist/inbox/memory.js +172 -0
  30. package/dist/inbox/ports.d.ts +150 -0
  31. package/dist/inbox/ports.js +1 -0
  32. package/dist/inbox/redact.d.ts +2 -0
  33. package/dist/inbox/redact.js +47 -0
  34. package/dist/inbox/schema.d.ts +1158 -0
  35. package/dist/inbox/schema.js +90 -0
  36. package/dist/inbox/watermark.d.ts +13 -0
  37. package/dist/inbox/watermark.js +6 -0
  38. package/dist/index.d.ts +30 -0
  39. package/dist/index.js +27 -0
  40. package/dist/ledger/ledger.d.ts +47 -0
  41. package/dist/ledger/ledger.js +224 -0
  42. package/dist/ports/index.d.ts +2 -0
  43. package/dist/ports/index.js +1 -0
  44. package/dist/ports/ledger-store.d.ts +53 -0
  45. package/dist/ports/ledger-store.js +1 -0
  46. package/dist/ports/runtime.d.ts +9 -0
  47. package/dist/ports/runtime.js +1 -0
  48. package/dist/providers/polar/events.d.ts +17 -0
  49. package/dist/providers/polar/events.js +213 -0
  50. package/dist/providers/polar/index.d.ts +50 -0
  51. package/dist/providers/polar/index.js +271 -0
  52. package/dist/providers/polar/signature.d.ts +23 -0
  53. package/dist/providers/polar/signature.js +52 -0
  54. package/dist/providers/port.d.ts +207 -0
  55. package/dist/providers/port.js +30 -0
  56. package/dist/providers/sepay/index.d.ts +34 -0
  57. package/dist/providers/sepay/index.js +241 -0
  58. package/dist/providers/sepay/order.d.ts +32 -0
  59. package/dist/providers/sepay/order.js +69 -0
  60. package/dist/providers/sepay/signature.d.ts +8 -0
  61. package/dist/providers/sepay/signature.js +51 -0
  62. package/dist/quote/conformance.d.ts +16 -0
  63. package/dist/quote/conformance.js +39 -0
  64. package/dist/quote/index.d.ts +3 -0
  65. package/dist/quote/index.js +3 -0
  66. package/dist/quote/steps.d.ts +54 -0
  67. package/dist/quote/steps.js +103 -0
  68. package/dist/quote/waterfall.d.ts +98 -0
  69. package/dist/quote/waterfall.js +82 -0
  70. package/dist/renewal/renewal.d.ts +69 -0
  71. package/dist/renewal/renewal.js +198 -0
  72. package/dist/stores/conformance.d.ts +22 -0
  73. package/dist/stores/conformance.js +269 -0
  74. package/dist/stores/memory.d.ts +19 -0
  75. package/dist/stores/memory.js +137 -0
  76. package/dist/stores/testing.d.ts +13 -0
  77. package/dist/stores/testing.js +13 -0
  78. package/dist/terms/conformance.d.ts +17 -0
  79. package/dist/terms/conformance.js +198 -0
  80. package/dist/terms/decide.d.ts +97 -0
  81. package/dist/terms/decide.js +176 -0
  82. package/dist/terms/drizzle.d.ts +12 -0
  83. package/dist/terms/drizzle.js +131 -0
  84. package/dist/terms/memory.d.ts +23 -0
  85. package/dist/terms/memory.js +126 -0
  86. package/dist/terms/plans.d.ts +85 -0
  87. package/dist/terms/plans.js +331 -0
  88. package/dist/terms/ports.d.ts +55 -0
  89. package/dist/terms/ports.js +1 -0
  90. package/dist/terms/rules.d.ts +11 -0
  91. package/dist/terms/rules.js +36 -0
  92. package/dist/terms/schema.d.ts +711 -0
  93. package/dist/terms/schema.js +70 -0
  94. package/dist/terms/snapshot.d.ts +20 -0
  95. package/dist/terms/snapshot.js +134 -0
  96. package/dist/terms/types.d.ts +85 -0
  97. package/dist/terms/types.js +4 -0
  98. package/docs/API.md +417 -0
  99. package/docs/SCHEMA.md +163 -0
  100. package/package.json +80 -4
@@ -0,0 +1,203 @@
1
+ /**
2
+ * `@tofound/billing/inbox/drizzle` — Postgres `IngestStore` over the ingest
3
+ * tables. Runs in the same Drizzle transaction as `createDrizzleLedgerStore`
4
+ * on the same `db`, so the inbox row, purchase and ledger entry commit
5
+ * together. Expects READ COMMITTED (the Postgres default).
6
+ */
7
+ import { and, asc, desc, eq, inArray, isNotNull, lt, lte, sql } from 'drizzle-orm';
8
+ export { createIngestTables, ingestTableNames } from './schema.js';
9
+ export function createDrizzleIngestStore(options) {
10
+ const { db } = options;
11
+ // The account column's TS type is the host's; the library reads and writes it as a string.
12
+ const inbox = options.tables.billingInbox;
13
+ const sessions = options.tables.billingCheckoutSessions;
14
+ const purchases = options.tables.billingPurchases;
15
+ const toInbox = (r) => ({
16
+ id: r.id,
17
+ provider: r.provider,
18
+ environment: r.environment,
19
+ eventId: r.eventId,
20
+ eventType: r.eventType,
21
+ subjectRef: r.subjectRef,
22
+ status: r.status,
23
+ attempts: r.attempts,
24
+ deliveryCount: r.deliveryCount,
25
+ nextAttemptAt: r.nextAttemptAt,
26
+ lastError: r.lastError,
27
+ reason: r.reason,
28
+ payload: r.payload,
29
+ occurredAt: r.occurredAt,
30
+ receivedAt: r.receivedAt,
31
+ lastReceivedAt: r.lastReceivedAt,
32
+ processedAt: r.processedAt,
33
+ });
34
+ const toSession = (r) => ({
35
+ id: r.id,
36
+ accountId: String(r.accountId),
37
+ provider: r.provider,
38
+ environment: r.environment,
39
+ status: r.status,
40
+ amount: { currency: r.currency, amountMinor: r.amountMinor },
41
+ credits: r.credits,
42
+ productRef: r.productRef,
43
+ externalId: r.externalId,
44
+ expiresAt: r.expiresAt,
45
+ completedAt: r.completedAt,
46
+ meta: r.meta ?? null,
47
+ createdAt: r.createdAt,
48
+ updatedAt: r.updatedAt,
49
+ });
50
+ const toPurchase = (r) => ({
51
+ id: r.id,
52
+ accountId: String(r.accountId),
53
+ provider: r.provider,
54
+ environment: r.environment,
55
+ externalId: r.externalId,
56
+ checkoutSessionId: r.checkoutSessionId,
57
+ status: r.status,
58
+ amount: { currency: r.currency, amountMinor: r.amountMinor },
59
+ credits: r.credits,
60
+ creditEntryId: r.creditEntryId,
61
+ clawedBack: r.clawedBack,
62
+ shortfall: r.shortfall,
63
+ reversals: r.reversals,
64
+ lastEventAt: r.lastEventAt,
65
+ lastEventRef: r.lastEventRef,
66
+ meta: r.meta ?? null,
67
+ createdAt: r.createdAt,
68
+ updatedAt: r.updatedAt,
69
+ });
70
+ const inboxKey = (provider, eventId) => and(eq(inbox.provider, provider), eq(inbox.eventId, eventId));
71
+ const purchaseKey = (provider, environment, externalId) => and(eq(purchases.provider, provider), eq(purchases.environment, environment), eq(purchases.externalId, externalId));
72
+ const reader = (ex) => ({
73
+ async getInbox(provider, eventId) {
74
+ const [row] = await ex.select().from(inbox).where(inboxKey(provider, eventId));
75
+ return row ? toInbox(row) : null;
76
+ },
77
+ async listInbox(opts) {
78
+ const filters = [
79
+ opts.statuses ? inArray(inbox.status, [...opts.statuses]) : undefined,
80
+ opts.receivedBefore ? lt(inbox.receivedAt, opts.receivedBefore) : undefined,
81
+ ].filter((f) => f !== undefined);
82
+ const rows = await ex
83
+ .select()
84
+ .from(inbox)
85
+ .where(filters.length ? and(...filters) : undefined)
86
+ .orderBy(desc(inbox.receivedAt))
87
+ .limit(opts.limit);
88
+ return rows.map(toInbox);
89
+ },
90
+ async listDue(now, limit, providers) {
91
+ if (providers?.length === 0)
92
+ return [];
93
+ const rows = await ex
94
+ .select()
95
+ .from(inbox)
96
+ .where(and(inArray(inbox.status, ['received', 'failed']), isNotNull(inbox.nextAttemptAt), lte(inbox.nextAttemptAt, now), providers ? inArray(inbox.provider, [...providers]) : undefined))
97
+ .orderBy(asc(inbox.nextAttemptAt))
98
+ .limit(limit);
99
+ return rows.map(toInbox);
100
+ },
101
+ async getSession(id) {
102
+ const [row] = await ex.select().from(sessions).where(eq(sessions.id, id));
103
+ return row ? toSession(row) : null;
104
+ },
105
+ async getPurchase(provider, environment, externalId) {
106
+ const [row] = await ex.select().from(purchases).where(purchaseKey(provider, environment, externalId));
107
+ return row ? toPurchase(row) : null;
108
+ },
109
+ });
110
+ const bind = (tx) => ({
111
+ ...reader(tx),
112
+ async receive(row) {
113
+ const inserted = await tx
114
+ .insert(inbox)
115
+ .values({ ...row, payload: row.payload ?? {} })
116
+ .onConflictDoNothing({ target: [inbox.provider, inbox.eventId] })
117
+ .returning();
118
+ if (inserted[0])
119
+ return { row: toInbox(inserted[0]), inserted: true };
120
+ const [counted] = await tx
121
+ .update(inbox)
122
+ .set({ deliveryCount: sql `${inbox.deliveryCount} + 1`, lastReceivedAt: row.lastReceivedAt, updatedAt: new Date() })
123
+ .where(inboxKey(row.provider, row.eventId))
124
+ .returning();
125
+ if (!counted)
126
+ throw new Error(`inbox row ${row.provider}/${row.eventId} vanished after conflict`);
127
+ return { row: toInbox(counted), inserted: false };
128
+ },
129
+ async lockInbox(provider, eventId) {
130
+ const [row] = await tx.select().from(inbox).where(inboxKey(provider, eventId)).for('update');
131
+ return row ? toInbox(row) : null;
132
+ },
133
+ async updateInbox(id, patch) {
134
+ await tx.update(inbox).set({ ...patch, updatedAt: new Date() }).where(eq(inbox.id, id));
135
+ },
136
+ async insertSession(s) {
137
+ await tx.insert(sessions).values({
138
+ id: s.id,
139
+ accountId: s.accountId,
140
+ provider: s.provider,
141
+ environment: s.environment,
142
+ status: s.status,
143
+ currency: s.amount.currency,
144
+ amountMinor: s.amount.amountMinor,
145
+ credits: s.credits,
146
+ productRef: s.productRef,
147
+ externalId: s.externalId,
148
+ expiresAt: s.expiresAt,
149
+ completedAt: s.completedAt,
150
+ meta: s.meta,
151
+ createdAt: s.createdAt,
152
+ updatedAt: s.updatedAt,
153
+ });
154
+ },
155
+ async lockSession(id) {
156
+ const [row] = await tx.select().from(sessions).where(eq(sessions.id, id)).for('update');
157
+ return row ? toSession(row) : null;
158
+ },
159
+ async updateSession(id, patch) {
160
+ await tx.update(sessions).set({ ...patch, updatedAt: new Date() }).where(eq(sessions.id, id));
161
+ },
162
+ async lockPurchase(provider, environment, externalId) {
163
+ const [row] = await tx.select().from(purchases).where(purchaseKey(provider, environment, externalId)).for('update');
164
+ return row ? toPurchase(row) : null;
165
+ },
166
+ async insertPurchase(p) {
167
+ const inserted = await tx
168
+ .insert(purchases)
169
+ .values({
170
+ id: p.id,
171
+ accountId: p.accountId,
172
+ provider: p.provider,
173
+ environment: p.environment,
174
+ externalId: p.externalId,
175
+ checkoutSessionId: p.checkoutSessionId,
176
+ status: p.status,
177
+ currency: p.amount.currency,
178
+ amountMinor: p.amount.amountMinor,
179
+ credits: p.credits,
180
+ creditEntryId: p.creditEntryId,
181
+ clawedBack: p.clawedBack,
182
+ shortfall: p.shortfall,
183
+ reversals: p.reversals,
184
+ lastEventAt: p.lastEventAt,
185
+ lastEventRef: p.lastEventRef,
186
+ meta: p.meta,
187
+ createdAt: p.createdAt,
188
+ updatedAt: p.updatedAt,
189
+ })
190
+ .onConflictDoNothing()
191
+ .returning({ id: purchases.id });
192
+ return { inserted: inserted.length === 1 };
193
+ },
194
+ async updatePurchase(id, patch) {
195
+ await tx.update(purchases).set({ ...patch, updatedAt: new Date() }).where(eq(purchases.id, id));
196
+ },
197
+ });
198
+ return {
199
+ transaction: (fn) => db.transaction((tx) => fn(tx)),
200
+ bind,
201
+ reader: () => reader(db),
202
+ };
203
+ }
@@ -0,0 +1,108 @@
1
+ import type { AccountId, BillingEvent, Money } from '../domain/types.js';
2
+ import type { Ledger } from '../ledger/ledger.js';
3
+ import type { Clock, IdGenerator } from '../ports/runtime.js';
4
+ import { type CheckoutRedirect, type InboundRequest, type IngestOutcome, type NormalizedEvent, type ProviderAdapter, type ProviderId, type ProviderResponse, type VerifiedDelivery } from '../providers/port.js';
5
+ import { type EventHandler, type PurchaseReversed } from './apply.js';
6
+ import { type CheckoutSession, type IngestReader, type IngestStore } from './ports.js';
7
+ /** Structured events for the host's metrics, alerts and bus (design §13). */
8
+ export type IngestEvent = {
9
+ type: 'billing.webhook';
10
+ provider: ProviderId;
11
+ eventType: string | null;
12
+ eventId: string | null;
13
+ outcome: 'applied' | 'ignored' | 'duplicate' | 'needs_review' | 'failed' | 'dead' | 'verify_failed';
14
+ reason: string | null;
15
+ }
16
+ /** An inbox row needs a human: `dead` (retry budget spent) or `needs_review`. */
17
+ | {
18
+ type: 'billing.alert';
19
+ alert: 'inbox_dead' | 'inbox_needs_review';
20
+ provider: ProviderId;
21
+ eventId: string;
22
+ reason: string | null;
23
+ }
24
+ /** A provider reversal was applied; `shortfall` > 0 is the host's shortfall policy input. */
25
+ | ({
26
+ type: 'refund_applied';
27
+ } & PurchaseReversed) | BillingEvent;
28
+ /** Sink errors are swallowed: an event is reported after its commit and cannot undo it. */
29
+ export type IngestEventSink = (event: IngestEvent) => void | Promise<void>;
30
+ export interface IngestPolicy {
31
+ /** Processing attempts before a row is `dead`. Default 8. */
32
+ maxAttempts?: number;
33
+ /** Delay before retry number `attempt` (1-based), in ms. Default exponential from 30 s, capped at 6 h. */
34
+ backoff?: (attempt: number) => number;
35
+ /** When a `received` row counts as abandoned by a crash and `sweep` re-enters it. Default 5 min. */
36
+ staleAfterMs?: number;
37
+ }
38
+ /**
39
+ * Called when a verified event matches no checkout session or purchase on
40
+ * this host (Lohi forwards those SePay IPNs to 2Novel). Gets the original
41
+ * request; its answer is relayed to the provider. A throw answers 5xx so
42
+ * the provider redelivers, and the redelivery calls the hook again.
43
+ */
44
+ export type UnmatchedHook = (input: {
45
+ provider: ProviderId;
46
+ request: InboundRequest;
47
+ delivery: VerifiedDelivery;
48
+ }) => Promise<ProviderResponse | void>;
49
+ export interface IngestOptions<TTx> {
50
+ adapters: readonly ProviderAdapter[];
51
+ /** Must share its transactions with the ledger's store. */
52
+ store: IngestStore<TTx>;
53
+ ledger: Ledger;
54
+ clock?: Clock;
55
+ ids?: IdGenerator;
56
+ policy?: IngestPolicy;
57
+ events?: IngestEventSink;
58
+ onUnmatched?: UnmatchedHook;
59
+ /** Appliers for event kinds the library does not apply itself (P1: `subscription.snapshot`). */
60
+ handlers?: Partial<Record<NormalizedEvent['kind'], EventHandler<TTx>>>;
61
+ }
62
+ export interface IngestResult extends IngestOutcome {
63
+ response: ProviderResponse;
64
+ }
65
+ export interface CreateCheckoutInput {
66
+ provider: ProviderId;
67
+ accountId: AccountId;
68
+ /** From the host's catalog — never from the client. */
69
+ amount: Money;
70
+ /** Credit minor units granted when paid. */
71
+ credits: number;
72
+ productRef?: string | null;
73
+ description: string;
74
+ successUrl: string;
75
+ errorUrl: string;
76
+ cancelUrl: string;
77
+ /** Session lifetime. Default 30 min. A payment after it still credits. */
78
+ ttlMs?: number;
79
+ meta?: Record<string, unknown> | null;
80
+ }
81
+ export interface SweepResult {
82
+ processed: number;
83
+ applied: number;
84
+ failed: number;
85
+ dead: number;
86
+ }
87
+ export interface Ingest {
88
+ /** One provider delivery, end to end. Never throws for a provider-caused failure. */
89
+ handle(provider: ProviderId, req: InboundRequest): Promise<IngestResult>;
90
+ /** A poll / client-proof confirmation (`PurchaseVerifier`); shares the webhook's event id and apply path. */
91
+ confirm(provider: ProviderId, proof: unknown): Promise<IngestOutcome>;
92
+ /** Re-run normalize + apply on the stored redacted payload. `applied`/`ignored` rows answer `duplicate`. */
93
+ replay(provider: ProviderId, eventId: string): Promise<IngestOutcome>;
94
+ /** Retry due `failed` rows and abandoned `received` rows. */
95
+ sweep(options?: {
96
+ now?: Date;
97
+ limit?: number;
98
+ }): Promise<SweepResult>;
99
+ /** Create a server-priced checkout session and the provider's redirect for it. */
100
+ createCheckout(input: CreateCheckoutInput): Promise<{
101
+ session: CheckoutSession;
102
+ redirect: CheckoutRedirect;
103
+ }>;
104
+ /** `pending → expired | cancelled`; a later verified capture still credits. No-op otherwise. */
105
+ closeCheckout(sessionId: string, status: 'expired' | 'cancelled'): Promise<CheckoutSession | null>;
106
+ reader(): IngestReader;
107
+ }
108
+ export declare function createIngest<TTx>(options: IngestOptions<TTx>): Ingest;