@pithy-sh/payments 0.6.1 → 0.7.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/README.md +6 -1
- package/dist/admin/coverage.d.ts.map +1 -1
- package/dist/admin/coverage.js +13 -7
- package/dist/admin/read.d.ts +60 -0
- package/dist/admin/read.d.ts.map +1 -1
- package/dist/admin/read.js +86 -2
- package/dist/audit/actions.d.ts +5 -0
- package/dist/audit/actions.d.ts.map +1 -1
- package/dist/audit/actions.js +6 -1
- package/dist/capability.d.ts +3 -3
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +14 -7
- package/dist/client/api.d.ts +25 -9
- package/dist/client/api.d.ts.map +1 -1
- package/dist/client/api.js +68 -12
- package/dist/client/hooks.d.ts +27 -39
- package/dist/client/hooks.d.ts.map +1 -1
- package/dist/client/hooks.js +166 -315
- package/dist/client/projection.d.ts +25 -18
- package/dist/client/projection.d.ts.map +1 -1
- package/dist/client/railChoice.d.ts +46 -0
- package/dist/client/railChoice.d.ts.map +1 -0
- package/dist/client/railChoice.js +48 -0
- package/dist/data/webhookEvent.d.ts +67 -0
- package/dist/data/webhookEvent.d.ts.map +1 -1
- package/dist/data/webhookEvent.js +76 -1
- package/dist/http/responses.d.ts +64 -0
- package/dist/http/responses.d.ts.map +1 -1
- package/dist/http/responses.js +34 -1
- package/dist/http/routes.d.ts +1 -0
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +64 -11
- package/dist/http/schemas.d.ts +19 -0
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +18 -1
- package/dist/http/scopes.d.ts +15 -6
- package/dist/http/scopes.d.ts.map +1 -1
- package/dist/http/scopes.js +55 -5
- package/dist/http/view.d.ts +9 -2
- package/dist/http/view.d.ts.map +1 -1
- package/dist/http/view.js +29 -1
- package/dist/http/webhookGuard.d.ts +7 -1
- package/dist/http/webhookGuard.d.ts.map +1 -1
- package/dist/http/webhookGuard.js +3 -2
- package/dist/migrations/0003_webhook_targets.d.ts +19 -0
- package/dist/migrations/0003_webhook_targets.d.ts.map +1 -0
- package/dist/migrations/0003_webhook_targets.js +29 -0
- package/dist/processing/activities.d.ts +9 -0
- package/dist/processing/activities.d.ts.map +1 -0
- package/dist/processing/activities.js +30 -0
- package/dist/projection/orphans.d.ts.map +1 -1
- package/dist/projection/orphans.js +15 -6
- package/dist/projection/targets.d.ts +50 -0
- package/dist/projection/targets.d.ts.map +1 -0
- package/dist/projection/targets.js +50 -0
- package/dist/purge/contribution.d.ts +32 -0
- package/dist/purge/contribution.d.ts.map +1 -0
- package/dist/purge/contribution.js +120 -0
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/dist/workflows/paddleSweep.d.ts.map +1 -1
- package/dist/workflows/paddleSweep.js +20 -9
- package/docs/lemon-squeezy.md +1 -1
- package/docs/paddle.md +2 -0
- package/package.json +6 -4
- package/src/admin/coverage.ts +13 -9
- package/src/admin/read.ts +135 -0
- package/src/audit/actions.ts +5 -0
- package/src/capability.ts +25 -15
- package/src/client/api.ts +74 -11
- package/src/client/hooks.ts +206 -301
- package/src/client/projection.ts +25 -18
- package/src/client/railChoice.ts +72 -0
- package/src/data/webhookEvent.ts +115 -0
- package/src/http/responses.ts +66 -0
- package/src/http/routes.ts +73 -11
- package/src/http/schemas.ts +26 -0
- package/src/http/scopes.ts +58 -6
- package/src/http/view.ts +31 -1
- package/src/http/webhookGuard.ts +23 -3
- package/src/migrations/0003_webhook_targets.ts +34 -0
- package/src/processing/activities.ts +34 -0
- package/src/projection/orphans.ts +28 -11
- package/src/projection/targets.ts +66 -0
- package/src/purge/contribution.ts +135 -0
- package/src/version.generated.ts +1 -1
- package/src/workflows/paddleSweep.ts +39 -14
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
|
|
4
|
+
import { personRowsExport } from "@pithy-sh/core/src/capability/personRows";
|
|
5
|
+
import type { RetainingPurgeContribution } from "@pithy-sh/core/src/capability/purge";
|
|
6
|
+
import { PaymentsEntitlement } from "../data/entitlement";
|
|
7
|
+
import { PaymentsMeterCounter } from "../data/meterCounter";
|
|
8
|
+
import { PaymentsOverride } from "../data/override";
|
|
9
|
+
import { PaymentsProviderAccount } from "../data/providerAccount";
|
|
10
|
+
import { PaymentsPurchase } from "../data/purchase";
|
|
11
|
+
import {
|
|
12
|
+
PAYMENTS_ENTITLEMENTS_TABLE,
|
|
13
|
+
PAYMENTS_METER_COUNTERS_TABLE,
|
|
14
|
+
PAYMENTS_OVERRIDES_TABLE,
|
|
15
|
+
PAYMENTS_PROVIDER_ACCOUNTS_TABLE,
|
|
16
|
+
PAYMENTS_PURCHASES_TABLE,
|
|
17
|
+
PAYMENTS_USAGE_REPORTS_TABLE,
|
|
18
|
+
} from "../data/tables";
|
|
19
|
+
import { PaymentsUsageReport } from "../data/usageReport";
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* What a person's purge means for `@pithy-sh/payments` (#814): **nothing is erased, and the export says so and why.**
|
|
23
|
+
*
|
|
24
|
+
* A purchase is a financial record, and the law that makes a business keep one for years — for tax, for an audit, for
|
|
25
|
+
* a chargeback — does not end when the buyer's account does. So this contribution **retains**: the purge records the
|
|
26
|
+
* step as retained with the basis below and erases no row of it, and the export answers for every row it keeps — the
|
|
27
|
+
* purchases, the entitlements they granted, the provider accounts that link them, and the overrides, meter counters
|
|
28
|
+
* and usage reports kept against the person.
|
|
29
|
+
*
|
|
30
|
+
* **Only a user subject's rows.** One `subjectId` column names people and organizations both; an organization's
|
|
31
|
+
* purchases are the organization's, and are not this person's whoever bought them.
|
|
32
|
+
*
|
|
33
|
+
* **Never the provider's payload.** A purchase keeps the verified notification it was projected from, and a rail's
|
|
34
|
+
* notification can carry what lets its holder act on the purchase — a Google Play purchase token among them. The
|
|
35
|
+
* export carries the projection, which is the person's record, and leaves the payload out. **Nor the token where the
|
|
36
|
+
* projection keeps it**: a Play row chains its renewals by the purchase token in `originalTransactionId`, and a row
|
|
37
|
+
* with no order yet — a subscription never paid for, a pending one-time purchase — is keyed on the token in
|
|
38
|
+
* `providerTransactionId`. The export carries neither: a Play row's family key is left out, and its transaction id
|
|
39
|
+
* only when it is the order id the provider reported.
|
|
40
|
+
*/
|
|
41
|
+
|
|
42
|
+
/** The one sentence the purge records with this step. */
|
|
43
|
+
export const PAYMENTS_PURGE_SUMMARY =
|
|
44
|
+
"Keeps the user's purchases, the entitlements they granted, the provider accounts that link them, and the overrides, meter counters and usage reports kept against them.";
|
|
45
|
+
|
|
46
|
+
/** Why, in the sentence the person is told. */
|
|
47
|
+
export const PAYMENTS_RETENTION_BASIS =
|
|
48
|
+
"Kept for tax and accounting records, which the law requires a business to hold after an account is closed.";
|
|
49
|
+
|
|
50
|
+
/** A person's rows only — an organization's share the id column and are the organization's. */
|
|
51
|
+
const USER = { subjectType: "user" } as const;
|
|
52
|
+
|
|
53
|
+
/** The order id a Play purchase reports — `latestOrderId` on a subscription, `orderId` on a one-time purchase. */
|
|
54
|
+
function playOrderId(payload: unknown): string | null {
|
|
55
|
+
if (typeof payload !== "object" || payload === null) return null;
|
|
56
|
+
const { latestOrderId, orderId } = payload as { latestOrderId?: unknown; orderId?: unknown };
|
|
57
|
+
const id = latestOrderId ?? orderId;
|
|
58
|
+
return typeof id === "string" && id !== "" ? id : null;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** A purchase row as the export carries it: a Google Play row never with its purchase token. */
|
|
62
|
+
export function redactPurchase(row: Record<string, unknown>): Record<string, unknown> {
|
|
63
|
+
if (row.rail !== "google") return row;
|
|
64
|
+
const order = playOrderId(row.payload);
|
|
65
|
+
return {
|
|
66
|
+
...row,
|
|
67
|
+
providerTransactionId: order !== null && row.providerTransactionId === order ? order : null,
|
|
68
|
+
originalTransactionId: null,
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** The user contribution `payments()` declares, over the D1 binding the payments tables live in. */
|
|
73
|
+
export function paymentsUserPurge(database = "DB"): RetainingPurgeContribution {
|
|
74
|
+
return {
|
|
75
|
+
subject: "user",
|
|
76
|
+
summary: PAYMENTS_PURGE_SUMMARY,
|
|
77
|
+
retain: { basis: PAYMENTS_RETENTION_BASIS },
|
|
78
|
+
export: personRowsExport({
|
|
79
|
+
capability: "payments",
|
|
80
|
+
database,
|
|
81
|
+
tables: [
|
|
82
|
+
{
|
|
83
|
+
table: PAYMENTS_PURCHASES_TABLE,
|
|
84
|
+
schema: PaymentsPurchase,
|
|
85
|
+
columns: ["subjectId"],
|
|
86
|
+
match: USER,
|
|
87
|
+
as: "purchases",
|
|
88
|
+
orderBy: "purchasedAt",
|
|
89
|
+
omit: ["payload"],
|
|
90
|
+
redact: redactPurchase,
|
|
91
|
+
},
|
|
92
|
+
{
|
|
93
|
+
table: PAYMENTS_ENTITLEMENTS_TABLE,
|
|
94
|
+
schema: PaymentsEntitlement,
|
|
95
|
+
columns: ["subjectId"],
|
|
96
|
+
match: USER,
|
|
97
|
+
as: "entitlements",
|
|
98
|
+
orderBy: "createdAt",
|
|
99
|
+
},
|
|
100
|
+
{
|
|
101
|
+
table: PAYMENTS_PROVIDER_ACCOUNTS_TABLE,
|
|
102
|
+
schema: PaymentsProviderAccount,
|
|
103
|
+
columns: ["subjectId"],
|
|
104
|
+
match: USER,
|
|
105
|
+
as: "providerAccounts",
|
|
106
|
+
orderBy: "createdAt",
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
table: PAYMENTS_OVERRIDES_TABLE,
|
|
110
|
+
schema: PaymentsOverride,
|
|
111
|
+
columns: ["subjectId"],
|
|
112
|
+
match: USER,
|
|
113
|
+
as: "overrides",
|
|
114
|
+
orderBy: "createdAt",
|
|
115
|
+
},
|
|
116
|
+
{
|
|
117
|
+
table: PAYMENTS_METER_COUNTERS_TABLE,
|
|
118
|
+
schema: PaymentsMeterCounter,
|
|
119
|
+
columns: ["subjectId"],
|
|
120
|
+
match: USER,
|
|
121
|
+
as: "meterCounters",
|
|
122
|
+
orderBy: "periodStart",
|
|
123
|
+
},
|
|
124
|
+
{
|
|
125
|
+
table: PAYMENTS_USAGE_REPORTS_TABLE,
|
|
126
|
+
schema: PaymentsUsageReport,
|
|
127
|
+
columns: ["subjectId"],
|
|
128
|
+
match: USER,
|
|
129
|
+
as: "usageReports",
|
|
130
|
+
orderBy: "createdAt",
|
|
131
|
+
},
|
|
132
|
+
],
|
|
133
|
+
}),
|
|
134
|
+
};
|
|
135
|
+
}
|
package/src/version.generated.ts
CHANGED
|
@@ -11,15 +11,20 @@ import { decodeSubjectReference } from "../data/subject";
|
|
|
11
11
|
import { PADDLE_EVENTS_CURSOR, PaymentsSyncCursor } from "../data/syncCursor";
|
|
12
12
|
import { PAYMENTS_SYNC_CURSORS_TABLE, PAYMENTS_WEBHOOK_EVENTS_TABLE, paymentsDatabase } from "../data/tables";
|
|
13
13
|
import {
|
|
14
|
+
encodeWebhookEventTargets,
|
|
14
15
|
isWebhookEventOutstanding,
|
|
16
|
+
NO_WEBHOOK_EVENT_TARGETS,
|
|
15
17
|
PaymentsWebhookEvent,
|
|
18
|
+
type PaymentsWebhookEventTargets,
|
|
16
19
|
WEBHOOK_EVENT_ORPHANED,
|
|
20
|
+
WEBHOOK_EVENT_QUARANTINED,
|
|
17
21
|
webhookEventState,
|
|
18
22
|
} from "../data/webhookEvent";
|
|
19
23
|
import { fulfillPurchase } from "../grants/apply";
|
|
20
24
|
import type { PaymentsLedgerPeer } from "../grants/ledgerSeam";
|
|
21
25
|
import { repairOrphanedEvents } from "../projection/orphans";
|
|
22
26
|
import { linkProviderAccount, resolveNotificationOwner } from "../projection/owner";
|
|
27
|
+
import { notificationTargets } from "../projection/targets";
|
|
23
28
|
import { projectPurchase } from "../projection/writer";
|
|
24
29
|
import { noteIsRepairable, noteText } from "../rails/contract";
|
|
25
30
|
import { type PaddleEnvironment, type PaddleHttpFetch, paddleHttpFetch } from "../rails/paddle/api";
|
|
@@ -308,12 +313,24 @@ async function record(
|
|
|
308
313
|
* it, so "handled" is tempting — but the guard reads this column, and the event's repair is precisely the
|
|
309
314
|
* redelivery that follows the missing link. See {@link abandon} and the module doc.
|
|
310
315
|
*/
|
|
311
|
-
async function complete(
|
|
316
|
+
async function complete(
|
|
317
|
+
d1: D1Database,
|
|
318
|
+
id: string,
|
|
319
|
+
now: Date,
|
|
320
|
+
finished: { readonly targets: PaymentsWebhookEventTargets } | { readonly note: string | undefined },
|
|
321
|
+
): Promise<void> {
|
|
312
322
|
await withD1Retry(() =>
|
|
313
323
|
paymentsDatabase(d1)
|
|
314
324
|
.updateTable(PAYMENTS_WEBHOOK_EVENTS_TABLE)
|
|
315
|
-
|
|
316
|
-
|
|
325
|
+
.set({
|
|
326
|
+
processedAt: now.getTime(),
|
|
327
|
+
error: "note" in finished ? (finished.note ?? null) : null,
|
|
328
|
+
// What it changed (#830): the rows it projected, or nothing for an event it decided to do nothing with.
|
|
329
|
+
projectedTargets: encodeWebhookEventTargets(
|
|
330
|
+
"targets" in finished ? finished.targets : NO_WEBHOOK_EVENT_TARGETS,
|
|
331
|
+
),
|
|
332
|
+
// biome-ignore lint/suspicious/noExplicitAny: encoded column values, not the app shape.
|
|
333
|
+
} as any)
|
|
317
334
|
.where("id", "=", id)
|
|
318
335
|
.execute(),
|
|
319
336
|
);
|
|
@@ -342,8 +359,11 @@ async function fail(d1: D1Database, id: string, attempt: number, error: string):
|
|
|
342
359
|
);
|
|
343
360
|
}
|
|
344
361
|
|
|
345
|
-
/**
|
|
346
|
-
|
|
362
|
+
/**
|
|
363
|
+
* The word an operator greps `error` for. One string, so the writer and a runbook cannot drift apart — and
|
|
364
|
+
* shared through `data/webhookEvent.ts`, because the management read classifies on it (#830).
|
|
365
|
+
*/
|
|
366
|
+
const QUARANTINED = WEBHOOK_EVENT_QUARANTINED;
|
|
347
367
|
|
|
348
368
|
/**
|
|
349
369
|
* The word for the other reason this sweep walks away from an event, likewise greppable.
|
|
@@ -636,7 +656,7 @@ export async function sweepPaddle(deps: PaddleSweepDeps): Promise<PaddleSweepRep
|
|
|
636
656
|
return report;
|
|
637
657
|
}
|
|
638
658
|
report.ignored += 1;
|
|
639
|
-
await complete(deps.d1, id, at, noteText(notification.note));
|
|
659
|
+
await complete(deps.d1, id, at, { note: noteText(notification.note) });
|
|
640
660
|
cursor = event.eventId;
|
|
641
661
|
continue;
|
|
642
662
|
}
|
|
@@ -673,13 +693,13 @@ export async function sweepPaddle(deps: PaddleSweepDeps): Promise<PaddleSweepRep
|
|
|
673
693
|
{ ...notification.event, ...subject },
|
|
674
694
|
{ config: deps.config, environment: deps.environment, now: at },
|
|
675
695
|
);
|
|
676
|
-
|
|
677
|
-
await projectPurchase(
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
696
|
+
const standing = notification.stateEvent
|
|
697
|
+
? await projectPurchase(
|
|
698
|
+
deps.d1,
|
|
699
|
+
{ ...notification.stateEvent, ...subject },
|
|
700
|
+
{ config: deps.config, environment: deps.environment, now: at },
|
|
701
|
+
)
|
|
702
|
+
: undefined;
|
|
683
703
|
// The same fulfillment the webhook path performs. A sweep that repaired a renewal and did not
|
|
684
704
|
// credit its coins would leave the entitlement right and the balance wrong, and nothing else would
|
|
685
705
|
// ever fix it — the renewal this sweep discovered is the one the webhook lost.
|
|
@@ -688,7 +708,12 @@ export async function sweepPaddle(deps: PaddleSweepDeps): Promise<PaddleSweepRep
|
|
|
688
708
|
((d1, value) =>
|
|
689
709
|
fulfillPurchase(d1, value, { config: deps.config, ledgerPeer: deps.ledgerPeer, now: () => at.getTime() }));
|
|
690
710
|
await fulfill(deps.d1, projection);
|
|
691
|
-
await complete(deps.d1, id, at
|
|
711
|
+
await complete(deps.d1, id, at, {
|
|
712
|
+
targets: notificationTargets(
|
|
713
|
+
{ event: notification.event, projection },
|
|
714
|
+
{ event: notification.stateEvent, projection: standing },
|
|
715
|
+
),
|
|
716
|
+
});
|
|
692
717
|
report.projected += 1;
|
|
693
718
|
cursor = event.eventId;
|
|
694
719
|
} catch (cause) {
|