@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.
Files changed (87) hide show
  1. package/README.md +6 -1
  2. package/dist/admin/coverage.d.ts.map +1 -1
  3. package/dist/admin/coverage.js +13 -7
  4. package/dist/admin/read.d.ts +60 -0
  5. package/dist/admin/read.d.ts.map +1 -1
  6. package/dist/admin/read.js +86 -2
  7. package/dist/audit/actions.d.ts +5 -0
  8. package/dist/audit/actions.d.ts.map +1 -1
  9. package/dist/audit/actions.js +6 -1
  10. package/dist/capability.d.ts +3 -3
  11. package/dist/capability.d.ts.map +1 -1
  12. package/dist/capability.js +14 -7
  13. package/dist/client/api.d.ts +25 -9
  14. package/dist/client/api.d.ts.map +1 -1
  15. package/dist/client/api.js +68 -12
  16. package/dist/client/hooks.d.ts +27 -39
  17. package/dist/client/hooks.d.ts.map +1 -1
  18. package/dist/client/hooks.js +166 -315
  19. package/dist/client/projection.d.ts +25 -18
  20. package/dist/client/projection.d.ts.map +1 -1
  21. package/dist/client/railChoice.d.ts +46 -0
  22. package/dist/client/railChoice.d.ts.map +1 -0
  23. package/dist/client/railChoice.js +48 -0
  24. package/dist/data/webhookEvent.d.ts +67 -0
  25. package/dist/data/webhookEvent.d.ts.map +1 -1
  26. package/dist/data/webhookEvent.js +76 -1
  27. package/dist/http/responses.d.ts +64 -0
  28. package/dist/http/responses.d.ts.map +1 -1
  29. package/dist/http/responses.js +34 -1
  30. package/dist/http/routes.d.ts +1 -0
  31. package/dist/http/routes.d.ts.map +1 -1
  32. package/dist/http/routes.js +64 -11
  33. package/dist/http/schemas.d.ts +19 -0
  34. package/dist/http/schemas.d.ts.map +1 -1
  35. package/dist/http/schemas.js +18 -1
  36. package/dist/http/scopes.d.ts +15 -6
  37. package/dist/http/scopes.d.ts.map +1 -1
  38. package/dist/http/scopes.js +55 -5
  39. package/dist/http/view.d.ts +9 -2
  40. package/dist/http/view.d.ts.map +1 -1
  41. package/dist/http/view.js +29 -1
  42. package/dist/http/webhookGuard.d.ts +7 -1
  43. package/dist/http/webhookGuard.d.ts.map +1 -1
  44. package/dist/http/webhookGuard.js +3 -2
  45. package/dist/migrations/0003_webhook_targets.d.ts +19 -0
  46. package/dist/migrations/0003_webhook_targets.d.ts.map +1 -0
  47. package/dist/migrations/0003_webhook_targets.js +29 -0
  48. package/dist/processing/activities.d.ts +9 -0
  49. package/dist/processing/activities.d.ts.map +1 -0
  50. package/dist/processing/activities.js +30 -0
  51. package/dist/projection/orphans.d.ts.map +1 -1
  52. package/dist/projection/orphans.js +15 -6
  53. package/dist/projection/targets.d.ts +50 -0
  54. package/dist/projection/targets.d.ts.map +1 -0
  55. package/dist/projection/targets.js +50 -0
  56. package/dist/purge/contribution.d.ts +32 -0
  57. package/dist/purge/contribution.d.ts.map +1 -0
  58. package/dist/purge/contribution.js +120 -0
  59. package/dist/version.generated.d.ts +1 -1
  60. package/dist/version.generated.js +1 -1
  61. package/dist/workflows/paddleSweep.d.ts.map +1 -1
  62. package/dist/workflows/paddleSweep.js +20 -9
  63. package/docs/lemon-squeezy.md +1 -1
  64. package/docs/paddle.md +2 -0
  65. package/package.json +6 -4
  66. package/src/admin/coverage.ts +13 -9
  67. package/src/admin/read.ts +135 -0
  68. package/src/audit/actions.ts +5 -0
  69. package/src/capability.ts +25 -15
  70. package/src/client/api.ts +74 -11
  71. package/src/client/hooks.ts +206 -301
  72. package/src/client/projection.ts +25 -18
  73. package/src/client/railChoice.ts +72 -0
  74. package/src/data/webhookEvent.ts +115 -0
  75. package/src/http/responses.ts +66 -0
  76. package/src/http/routes.ts +73 -11
  77. package/src/http/schemas.ts +26 -0
  78. package/src/http/scopes.ts +58 -6
  79. package/src/http/view.ts +31 -1
  80. package/src/http/webhookGuard.ts +23 -3
  81. package/src/migrations/0003_webhook_targets.ts +34 -0
  82. package/src/processing/activities.ts +34 -0
  83. package/src/projection/orphans.ts +28 -11
  84. package/src/projection/targets.ts +66 -0
  85. package/src/purge/contribution.ts +135 -0
  86. package/src/version.generated.ts +1 -1
  87. package/src/workflows/paddleSweep.ts +39 -14
@@ -0,0 +1,19 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { Migration } from "kysely/migration";
4
+ /**
5
+ * What each webhook event changed, and the index its management read pages on (#830).
6
+ *
7
+ * **A new migration, because `0001` and `0002` are history.** Both have been running since they shipped, and
8
+ * reshaping either would reshape a database somebody is already running.
9
+ *
10
+ * - `pithy_payments_webhook_events.projected_targets` — the purchase and subscription row ids an event changed
11
+ * when it finished, as JSON (`data/webhookEvent.ts`'s `PaymentsWebhookEventTargets`). Nullable, and null on
12
+ * every row that exists when this runs: those events finished before anything recorded what they touched,
13
+ * and no store is asked again to reconstruct it. Null is *unrecorded*; two empty lists is *changed nothing*.
14
+ * - `pithy_payments_webhook_events_received_idx` on `(receivedAt, id)` — `GET {base}/admin/webhook-events`
15
+ * pages newest received first, keyset on the id like every listing here. The pending index `0001` made
16
+ * leads on `processedAt` and serves the repair passes, not a page of everything.
17
+ */
18
+ export declare const payments_0003_webhook_targets: Migration;
19
+ //# sourceMappingURL=0003_webhook_targets.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"0003_webhook_targets.d.ts","sourceRoot":"","sources":["../../src/migrations/0003_webhook_targets.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAa3C,CAAC"}
@@ -0,0 +1,29 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ //#region src/migrations/0003_webhook_targets.ts
4
+ /**
5
+ * What each webhook event changed, and the index its management read pages on (#830).
6
+ *
7
+ * **A new migration, because `0001` and `0002` are history.** Both have been running since they shipped, and
8
+ * reshaping either would reshape a database somebody is already running.
9
+ *
10
+ * - `pithy_payments_webhook_events.projected_targets` — the purchase and subscription row ids an event changed
11
+ * when it finished, as JSON (`data/webhookEvent.ts`'s `PaymentsWebhookEventTargets`). Nullable, and null on
12
+ * every row that exists when this runs: those events finished before anything recorded what they touched,
13
+ * and no store is asked again to reconstruct it. Null is *unrecorded*; two empty lists is *changed nothing*.
14
+ * - `pithy_payments_webhook_events_received_idx` on `(receivedAt, id)` — `GET {base}/admin/webhook-events`
15
+ * pages newest received first, keyset on the id like every listing here. The pending index `0001` made
16
+ * leads on `processedAt` and serves the repair passes, not a page of everything.
17
+ */
18
+ const payments_0003_webhook_targets = {
19
+ up: async (db) => {
20
+ await db.schema.alterTable("pithyPaymentsWebhookEvents").addColumn("projectedTargets", "text").execute();
21
+ await db.schema.createIndex("pithyPaymentsWebhookEventsReceivedIdx").on("pithyPaymentsWebhookEvents").columns(["receivedAt", "id"]).execute();
22
+ },
23
+ down: async (db) => {
24
+ await db.schema.dropIndex("pithyPaymentsWebhookEventsReceivedIdx").execute();
25
+ await db.schema.alterTable("pithyPaymentsWebhookEvents").dropColumn("projectedTargets").execute();
26
+ }
27
+ };
28
+ //#endregion
29
+ export { payments_0003_webhook_targets };
@@ -0,0 +1,9 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { ProcessingActivityInput, ProcessingRecipientInput } from "@pithy-sh/core/src/processing/activity";
4
+ import { type PaymentsRail } from "../data/rail";
5
+ /** Every rail the config turns on, as a recipient of the purchases made on it. */
6
+ export declare function railRecipients(rails: Readonly<Record<PaymentsRail, boolean>>): ProcessingRecipientInput[];
7
+ /** What payments does with personal data: it sells, and keeps each purchase and what it granted. */
8
+ export declare function paymentsProcessing(rails: Readonly<Record<PaymentsRail, boolean>>): ProcessingActivityInput[];
9
+ //# sourceMappingURL=activities.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"activities.d.ts","sourceRoot":"","sources":["../../src/processing/activities.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AAChH,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAWjE,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,GAAG,wBAAwB,EAAE,CAKzG;AAED,oGAAoG;AACpG,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,GAAG,uBAAuB,EAAE,CAS5G"}
@@ -0,0 +1,30 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { PAYMENTS_RAILS } from "../data/rail.js";
4
+ //#region src/processing/activities.ts
5
+ /** Each rail, as an auditor would name the company behind it. */
6
+ const RAIL_NAMES = {
7
+ apple: "Apple App Store",
8
+ google: "Google Play",
9
+ stripe: "Stripe",
10
+ lemonSqueezy: "Lemon Squeezy",
11
+ paddle: "Paddle"
12
+ };
13
+ /** Every rail the config turns on, as a recipient of the purchases made on it. */
14
+ function railRecipients(rails) {
15
+ return PAYMENTS_RAILS.filter((rail) => rails[rail]).map((rail) => ({
16
+ name: RAIL_NAMES[rail],
17
+ receives: "Each purchase made on it, and the account id it is made for."
18
+ }));
19
+ }
20
+ /** What payments does with personal data: it sells, and keeps each purchase and what it granted. */
21
+ function paymentsProcessing(rails) {
22
+ return [{
23
+ id: "payments.purchases",
24
+ purpose: "Sell to a person, keep each purchase and what it entitles them to, and keep it for tax law.",
25
+ legalBasis: "contract",
26
+ recipients: railRecipients(rails)
27
+ }];
28
+ }
29
+ //#endregion
30
+ export { paymentsProcessing, railRecipients };
@@ -1 +1 @@
1
- {"version":3,"file":"orphans.d.ts","sourceRoot":"","sources":["../../src/projection/orphans.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,OAAO,EAAE,KAAK,kBAAkB,EAAmB,MAAM,UAAU,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,iHAAiH;AACjH,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,MAAM,EAAE,cAAc,CAAC;IACvB,oFAAoF;IACpF,WAAW,EAAE,mBAAmB,CAAC;IACjC,iBAAiB;IACjB,GAAG,EAAE,IAAI,CAAC;IACV;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAAC;IACzF,yGAAyG;IACzG,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,6FAA6F;AAC7F,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,sGAAsG;IACtG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,UAAU,EACd,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,eAAe,CAAC,CA2E1B"}
1
+ {"version":3,"file":"orphans.d.ts","sourceRoot":"","sources":["../../src/projection/orphans.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AASjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAG9D,OAAO,EAAE,KAAK,kBAAkB,EAAmB,MAAM,UAAU,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,iHAAiH;AACjH,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,MAAM,EAAE,cAAc,CAAC;IACvB,oFAAoF;IACpF,WAAW,EAAE,mBAAmB,CAAC;IACjC,iBAAiB;IACjB,GAAG,EAAE,IAAI,CAAC;IACV;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAAC;IACzF,yGAAyG;IACzG,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,6FAA6F;AAC7F,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,sGAAsG;IACtG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,UAAU,EACd,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,eAAe,CAAC,CAoF1B"}
@@ -1,8 +1,9 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
- import { PaymentsWebhookEvent, WEBHOOK_EVENT_ORPHANED, webhookEventAwaitsOwner } from "../data/webhookEvent.js";
3
+ import { PaymentsWebhookEvent, WEBHOOK_EVENT_ORPHANED, encodeWebhookEventTargets, webhookEventAwaitsOwner } from "../data/webhookEvent.js";
4
4
  import { PAYMENTS_WEBHOOK_EVENTS_TABLE, paymentsDatabase } from "../data/tables.js";
5
5
  import { resolveNotificationOwner } from "./owner.js";
6
+ import { notificationTargets } from "./targets.js";
6
7
  import { projectPurchase } from "./writer.js";
7
8
  import { withD1Retry } from "@pithy-sh/core/src/data/withD1Retry";
8
9
  //#region src/projection/orphans.ts
@@ -112,6 +113,7 @@ async function repairOrphanedEvents(d1, rail, options) {
112
113
  continue;
113
114
  }
114
115
  let projection;
116
+ let standing;
115
117
  try {
116
118
  projection = await projectPurchase(d1, {
117
119
  ...notification.event,
@@ -121,20 +123,26 @@ async function repairOrphanedEvents(d1, rail, options) {
121
123
  environment: options.environment,
122
124
  now: options.now
123
125
  });
124
- if (notification.stateEvent) await projectPurchase(d1, {
126
+ standing = notification.stateEvent ? await projectPurchase(d1, {
125
127
  ...notification.stateEvent,
126
128
  ...subject
127
129
  }, {
128
130
  config: options.config,
129
131
  environment: options.environment,
130
132
  now: options.now
131
- });
133
+ }) : void 0;
132
134
  await options.fulfill?.(projection);
133
135
  } catch {
134
136
  waiting += 1;
135
137
  continue;
136
138
  }
137
- await finish(d1, row.id, options.now);
139
+ await finish(d1, row.id, options.now, notificationTargets({
140
+ event: notification.event,
141
+ projection
142
+ }, {
143
+ event: notification.stateEvent,
144
+ projection: standing
145
+ }));
138
146
  projected.push(row.providerEventId);
139
147
  }
140
148
  return {
@@ -154,10 +162,11 @@ async function repairOrphanedEvents(d1, rail, options) {
154
162
  * `abandonedAt` is left exactly where it was. A sweep having given up on this row is a fact about that pass
155
163
  * and a record of how close the purchase came to being lost; `finished` already wins over it by construction.
156
164
  */
157
- async function finish(d1, id, now) {
165
+ async function finish(d1, id, now, targets) {
158
166
  await withD1Retry(() => paymentsDatabase(d1).updateTable(PAYMENTS_WEBHOOK_EVENTS_TABLE).set({
159
167
  processedAt: now.getTime(),
160
- error: null
168
+ error: null,
169
+ projectedTargets: encodeWebhookEventTargets(targets)
161
170
  }).where("id", "=", id).execute());
162
171
  }
163
172
  //#endregion
@@ -0,0 +1,50 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { PaymentsWebhookEventTargets } from "../data/webhookEvent";
4
+ import type { PurchaseProjection } from "./writer";
5
+ /** What the split reads off one projection: whether it wrote, and the row it wrote to or read. */
6
+ export type TargetedProjection = {
7
+ readonly outcome: PurchaseProjection["outcome"];
8
+ readonly purchase: Pick<PurchaseProjection["purchase"], "id" | "type" | "providerEventAt">;
9
+ };
10
+ /** One projection a finishing event made, beside the provider time of the event it projected. */
11
+ export type ProjectedEvent = {
12
+ readonly projection: TargetedProjection;
13
+ /** The `providerEventAt` of the event handed to the writer — the version the row carries if this event wrote it. */
14
+ readonly eventAt: Date;
15
+ };
16
+ /**
17
+ * Every purchase and subscription row a set of projections changed — what a finishing event records about
18
+ * itself (#830).
19
+ *
20
+ * **Changed, not touched.** A projection answering `ignored` wrote nothing on this attempt, but that is two
21
+ * cases. A row strictly newer than the event was moved by some later event, so listing it would claim a change
22
+ * that did not happen. A row carrying the event's *own* version is this event's write, made on an earlier
23
+ * attempt that projected and then failed after — a fulfillment that threw, the second half of a Lemon
24
+ * Squeezy refund — and left the row unfinished for the redelivery, the sweep or the repair to finish. That
25
+ * row is listed: recording two empty lists there would say the event finished and changed nothing, which is
26
+ * the one wrong answer worse than none.
27
+ *
28
+ * The split is on the row's own `type`, the same narrowing `payments:subscriptions:read` applies, so the two
29
+ * lists are disjoint and each id is one a client holding that read can open. A row written twice by one
30
+ * delivery is listed once, in the order it was first written.
31
+ */
32
+ export declare function projectionTargets(projected: readonly ProjectedEvent[]): PaymentsWebhookEventTargets;
33
+ /** The provider time of an event, which is all {@link notificationTargets} reads off one. */
34
+ type Timed = {
35
+ readonly providerEventAt: Date;
36
+ };
37
+ /**
38
+ * {@link projectionTargets} for the one shape every finishing path has: a notification's charge, and the
39
+ * standing beside it where the rail sent one. Each projection travels with the event it projected, so a
40
+ * caller cannot hand the charge's time to the standing's row.
41
+ */
42
+ export declare function notificationTargets(charge: {
43
+ readonly event: Timed;
44
+ readonly projection: TargetedProjection;
45
+ }, standing: {
46
+ readonly event?: Timed | null;
47
+ readonly projection?: TargetedProjection | undefined;
48
+ }): PaymentsWebhookEventTargets;
49
+ export {};
50
+ //# sourceMappingURL=targets.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"targets.d.ts","sourceRoot":"","sources":["../../src/projection/targets.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD,kGAAkG;AAClG,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,kBAAkB,CAAC,UAAU,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,iBAAiB,CAAC,CAAC;CAC5F,CAAC;AAEF,iGAAiG;AACjG,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,oHAAoH;IACpH,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,GAAG,2BAA2B,CAWnG;AAED,6FAA6F;AAC7F,KAAK,KAAK,GAAG;IAAE,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAA;CAAE,CAAC;AAEhD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAA;CAAE,EAC1E,QAAQ,EAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAA;CAAE,GAChG,2BAA2B,CAM7B"}
@@ -0,0 +1,50 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ //#region src/projection/targets.ts
4
+ /**
5
+ * Every purchase and subscription row a set of projections changed — what a finishing event records about
6
+ * itself (#830).
7
+ *
8
+ * **Changed, not touched.** A projection answering `ignored` wrote nothing on this attempt, but that is two
9
+ * cases. A row strictly newer than the event was moved by some later event, so listing it would claim a change
10
+ * that did not happen. A row carrying the event's *own* version is this event's write, made on an earlier
11
+ * attempt that projected and then failed after — a fulfillment that threw, the second half of a Lemon
12
+ * Squeezy refund — and left the row unfinished for the redelivery, the sweep or the repair to finish. That
13
+ * row is listed: recording two empty lists there would say the event finished and changed nothing, which is
14
+ * the one wrong answer worse than none.
15
+ *
16
+ * The split is on the row's own `type`, the same narrowing `payments:subscriptions:read` applies, so the two
17
+ * lists are disjoint and each id is one a client holding that read can open. A row written twice by one
18
+ * delivery is listed once, in the order it was first written.
19
+ */
20
+ function projectionTargets(projected) {
21
+ const purchaseIds = [];
22
+ const subscriptionIds = [];
23
+ for (const { projection, eventAt } of projected) {
24
+ if (projection.outcome === "ignored" && projection.purchase.providerEventAt.getTime() !== eventAt.getTime()) continue;
25
+ const list = projection.purchase.type === "subscription" ? subscriptionIds : purchaseIds;
26
+ if (!list.includes(projection.purchase.id)) list.push(projection.purchase.id);
27
+ }
28
+ return {
29
+ purchaseIds,
30
+ subscriptionIds
31
+ };
32
+ }
33
+ /**
34
+ * {@link projectionTargets} for the one shape every finishing path has: a notification's charge, and the
35
+ * standing beside it where the rail sent one. Each projection travels with the event it projected, so a
36
+ * caller cannot hand the charge's time to the standing's row.
37
+ */
38
+ function notificationTargets(charge, standing) {
39
+ const projected = [{
40
+ projection: charge.projection,
41
+ eventAt: charge.event.providerEventAt
42
+ }];
43
+ if (standing.projection !== void 0 && standing.event) projected.push({
44
+ projection: standing.projection,
45
+ eventAt: standing.event.providerEventAt
46
+ });
47
+ return projectionTargets(projected);
48
+ }
49
+ //#endregion
50
+ export { notificationTargets, projectionTargets };
@@ -0,0 +1,32 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { RetainingPurgeContribution } from "@pithy-sh/core/src/capability/purge";
4
+ /**
5
+ * What a person's purge means for `@pithy-sh/payments` (#814): **nothing is erased, and the export says so and why.**
6
+ *
7
+ * A purchase is a financial record, and the law that makes a business keep one for years — for tax, for an audit, for
8
+ * a chargeback — does not end when the buyer's account does. So this contribution **retains**: the purge records the
9
+ * step as retained with the basis below and erases no row of it, and the export answers for every row it keeps — the
10
+ * purchases, the entitlements they granted, the provider accounts that link them, and the overrides, meter counters
11
+ * and usage reports kept against the person.
12
+ *
13
+ * **Only a user subject's rows.** One `subjectId` column names people and organizations both; an organization's
14
+ * purchases are the organization's, and are not this person's whoever bought them.
15
+ *
16
+ * **Never the provider's payload.** A purchase keeps the verified notification it was projected from, and a rail's
17
+ * notification can carry what lets its holder act on the purchase — a Google Play purchase token among them. The
18
+ * export carries the projection, which is the person's record, and leaves the payload out. **Nor the token where the
19
+ * projection keeps it**: a Play row chains its renewals by the purchase token in `originalTransactionId`, and a row
20
+ * with no order yet — a subscription never paid for, a pending one-time purchase — is keyed on the token in
21
+ * `providerTransactionId`. The export carries neither: a Play row's family key is left out, and its transaction id
22
+ * only when it is the order id the provider reported.
23
+ */
24
+ /** The one sentence the purge records with this step. */
25
+ export declare const PAYMENTS_PURGE_SUMMARY = "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.";
26
+ /** Why, in the sentence the person is told. */
27
+ export declare const PAYMENTS_RETENTION_BASIS = "Kept for tax and accounting records, which the law requires a business to hold after an account is closed.";
28
+ /** A purchase row as the export carries it: a Google Play row never with its purchase token. */
29
+ export declare function redactPurchase(row: Record<string, unknown>): Record<string, unknown>;
30
+ /** The user contribution `payments()` declares, over the D1 binding the payments tables live in. */
31
+ export declare function paymentsUserPurge(database?: string): RetainingPurgeContribution;
32
+ //# sourceMappingURL=contribution.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"contribution.d.ts","sourceRoot":"","sources":["../../src/purge/contribution.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AAgBtF;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,yDAAyD;AACzD,eAAO,MAAM,sBAAsB,4KACwI,CAAC;AAE5K,+CAA+C;AAC/C,eAAO,MAAM,wBAAwB,+GACyE,CAAC;AAa/G,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQpF;AAED,oGAAoG;AACpG,wBAAgB,iBAAiB,CAAC,QAAQ,SAAO,GAAG,0BAA0B,CA8D7E"}
@@ -0,0 +1,120 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { PaymentsEntitlement } from "../data/entitlement.js";
4
+ import { PaymentsMeterCounter } from "../data/meterCounter.js";
5
+ import { PaymentsOverride } from "../data/override.js";
6
+ import { PaymentsProviderAccount } from "../data/providerAccount.js";
7
+ import { PaymentsPurchase } from "../data/purchase.js";
8
+ import { PaymentsUsageReport } from "../data/usageReport.js";
9
+ import { PAYMENTS_ENTITLEMENTS_TABLE, PAYMENTS_METER_COUNTERS_TABLE, PAYMENTS_OVERRIDES_TABLE, PAYMENTS_PROVIDER_ACCOUNTS_TABLE, PAYMENTS_PURCHASES_TABLE, PAYMENTS_USAGE_REPORTS_TABLE } from "../data/tables.js";
10
+ import { personRowsExport } from "@pithy-sh/core/src/capability/personRows";
11
+ //#region src/purge/contribution.ts
12
+ /**
13
+ * What a person's purge means for `@pithy-sh/payments` (#814): **nothing is erased, and the export says so and why.**
14
+ *
15
+ * A purchase is a financial record, and the law that makes a business keep one for years — for tax, for an audit, for
16
+ * a chargeback — does not end when the buyer's account does. So this contribution **retains**: the purge records the
17
+ * step as retained with the basis below and erases no row of it, and the export answers for every row it keeps — the
18
+ * purchases, the entitlements they granted, the provider accounts that link them, and the overrides, meter counters
19
+ * and usage reports kept against the person.
20
+ *
21
+ * **Only a user subject's rows.** One `subjectId` column names people and organizations both; an organization's
22
+ * purchases are the organization's, and are not this person's whoever bought them.
23
+ *
24
+ * **Never the provider's payload.** A purchase keeps the verified notification it was projected from, and a rail's
25
+ * notification can carry what lets its holder act on the purchase — a Google Play purchase token among them. The
26
+ * export carries the projection, which is the person's record, and leaves the payload out. **Nor the token where the
27
+ * projection keeps it**: a Play row chains its renewals by the purchase token in `originalTransactionId`, and a row
28
+ * with no order yet — a subscription never paid for, a pending one-time purchase — is keyed on the token in
29
+ * `providerTransactionId`. The export carries neither: a Play row's family key is left out, and its transaction id
30
+ * only when it is the order id the provider reported.
31
+ */
32
+ /** The one sentence the purge records with this step. */
33
+ const PAYMENTS_PURGE_SUMMARY = "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.";
34
+ /** Why, in the sentence the person is told. */
35
+ const PAYMENTS_RETENTION_BASIS = "Kept for tax and accounting records, which the law requires a business to hold after an account is closed.";
36
+ /** A person's rows only — an organization's share the id column and are the organization's. */
37
+ const USER = { subjectType: "user" };
38
+ /** The order id a Play purchase reports — `latestOrderId` on a subscription, `orderId` on a one-time purchase. */
39
+ function playOrderId(payload) {
40
+ if (typeof payload !== "object" || payload === null) return null;
41
+ const { latestOrderId, orderId } = payload;
42
+ const id = latestOrderId ?? orderId;
43
+ return typeof id === "string" && id !== "" ? id : null;
44
+ }
45
+ /** A purchase row as the export carries it: a Google Play row never with its purchase token. */
46
+ function redactPurchase(row) {
47
+ if (row.rail !== "google") return row;
48
+ const order = playOrderId(row.payload);
49
+ return {
50
+ ...row,
51
+ providerTransactionId: order !== null && row.providerTransactionId === order ? order : null,
52
+ originalTransactionId: null
53
+ };
54
+ }
55
+ /** The user contribution `payments()` declares, over the D1 binding the payments tables live in. */
56
+ function paymentsUserPurge(database = "DB") {
57
+ return {
58
+ subject: "user",
59
+ summary: PAYMENTS_PURGE_SUMMARY,
60
+ retain: { basis: PAYMENTS_RETENTION_BASIS },
61
+ export: personRowsExport({
62
+ capability: "payments",
63
+ database,
64
+ tables: [
65
+ {
66
+ table: PAYMENTS_PURCHASES_TABLE,
67
+ schema: PaymentsPurchase,
68
+ columns: ["subjectId"],
69
+ match: USER,
70
+ as: "purchases",
71
+ orderBy: "purchasedAt",
72
+ omit: ["payload"],
73
+ redact: redactPurchase
74
+ },
75
+ {
76
+ table: PAYMENTS_ENTITLEMENTS_TABLE,
77
+ schema: PaymentsEntitlement,
78
+ columns: ["subjectId"],
79
+ match: USER,
80
+ as: "entitlements",
81
+ orderBy: "createdAt"
82
+ },
83
+ {
84
+ table: PAYMENTS_PROVIDER_ACCOUNTS_TABLE,
85
+ schema: PaymentsProviderAccount,
86
+ columns: ["subjectId"],
87
+ match: USER,
88
+ as: "providerAccounts",
89
+ orderBy: "createdAt"
90
+ },
91
+ {
92
+ table: PAYMENTS_OVERRIDES_TABLE,
93
+ schema: PaymentsOverride,
94
+ columns: ["subjectId"],
95
+ match: USER,
96
+ as: "overrides",
97
+ orderBy: "createdAt"
98
+ },
99
+ {
100
+ table: PAYMENTS_METER_COUNTERS_TABLE,
101
+ schema: PaymentsMeterCounter,
102
+ columns: ["subjectId"],
103
+ match: USER,
104
+ as: "meterCounters",
105
+ orderBy: "periodStart"
106
+ },
107
+ {
108
+ table: PAYMENTS_USAGE_REPORTS_TABLE,
109
+ schema: PaymentsUsageReport,
110
+ columns: ["subjectId"],
111
+ match: USER,
112
+ as: "usageReports",
113
+ orderBy: "createdAt"
114
+ }
115
+ ]
116
+ })
117
+ };
118
+ }
119
+ //#endregion
120
+ export { PAYMENTS_PURGE_SUMMARY, PAYMENTS_RETENTION_BASIS, paymentsUserPurge, redactPurchase };
@@ -3,5 +3,5 @@
3
3
  /** This package's npm name — the join key against a release feed. */
4
4
  export declare const PACKAGE_NAME = "@pithy-sh/payments";
5
5
  /** This package's version, stamped from its own package.json at generation time. */
6
- export declare const PACKAGE_VERSION = "0.6.1";
6
+ export declare const PACKAGE_VERSION = "0.7.0";
7
7
  //# sourceMappingURL=version.generated.d.ts.map
@@ -4,6 +4,6 @@
4
4
  /** This package's npm name — the join key against a release feed. */
5
5
  const PACKAGE_NAME = "@pithy-sh/payments";
6
6
  /** This package's version, stamped from its own package.json at generation time. */
7
- const PACKAGE_VERSION = "0.6.1";
7
+ const PACKAGE_VERSION = "0.7.0";
8
8
  //#endregion
9
9
  export { PACKAGE_NAME, PACKAGE_VERSION };
@@ -1 +1 @@
1
- {"version":3,"file":"paddleSweep.d.ts","sourceRoot":"","sources":["../../src/workflows/paddleSweep.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAU5D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAK/D,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAmB,MAAM,qBAAqB,CAAC;AACpG,OAAO,EAAE,2BAA2B,EAAqB,MAAM,wBAAwB,CAAC;AAIxF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AAEH,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,EAAE,EAAE,UAAU,CAAC;IACf,wEAAwE;IACxE,MAAM,EAAE,cAAc,CAAC;IACvB,uGAAuG;IACvG,WAAW,EAAE,mBAAmB,CAAC;IACjC,8EAA8E;IAC9E,WAAW,EAAE,yBAAyB,CAAC;IACvC,qCAAqC;IACrC,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,6FAA6F;IAC7F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB;IACjB,GAAG,IAAI,IAAI,CAAC;IACZ,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB,qBAAqB;IACrB,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,oGAAoG;IACpG,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClG,wHAAwH;IACxH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,yFAAyF;AACzF,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;OAYG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,2FAA2F;IAC3F,SAAS,EAAE,MAAM,CAAC;IAClB,+GAA+G;IAC/G,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;OAUG;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,uEAAuE;IACvE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,gFAAgF;IAChF,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAKD;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAmT3C;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmNnF;AAED,2GAA2G;AAC3G,OAAO,EAAE,2BAA2B,EAAE,CAAC"}
1
+ {"version":3,"file":"paddleSweep.d.ts","sourceRoot":"","sources":["../../src/workflows/paddleSweep.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAc5D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAM/D,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAmB,MAAM,qBAAqB,CAAC;AACpG,OAAO,EAAE,2BAA2B,EAAqB,MAAM,wBAAwB,CAAC;AAIxF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AAEH,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,EAAE,EAAE,UAAU,CAAC;IACf,wEAAwE;IACxE,MAAM,EAAE,cAAc,CAAC;IACvB,uGAAuG;IACvG,WAAW,EAAE,mBAAmB,CAAC;IACjC,8EAA8E;IAC9E,WAAW,EAAE,yBAAyB,CAAC;IACvC,qCAAqC;IACrC,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,6FAA6F;IAC7F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB;IACjB,GAAG,IAAI,IAAI,CAAC;IACZ,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB,qBAAqB;IACrB,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,oGAAoG;IACpG,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClG,wHAAwH;IACxH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,yFAAyF;AACzF,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;OAYG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,2FAA2F;IAC3F,SAAS,EAAE,MAAM,CAAC;IAClB,+GAA+G;IAC/G,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;OAUG;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,uEAAuE;IACvE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,gFAAgF;IAChF,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAKD;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAkU3C;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAwNnF;AAED,2GAA2G;AAC3G,OAAO,EAAE,2BAA2B,EAAE,CAAC"}
@@ -3,10 +3,11 @@
3
3
  import { decodeSubjectReference } from "../data/subject.js";
4
4
  import { railEnabled } from "../config/config.js";
5
5
  import { PADDLE_EVENTS_CURSOR, PaymentsSyncCursor } from "../data/syncCursor.js";
6
- import { PaymentsWebhookEvent, WEBHOOK_EVENT_ORPHANED, isWebhookEventOutstanding, webhookEventState } from "../data/webhookEvent.js";
6
+ import { NO_WEBHOOK_EVENT_TARGETS, PaymentsWebhookEvent, WEBHOOK_EVENT_ORPHANED, WEBHOOK_EVENT_QUARANTINED, encodeWebhookEventTargets, isWebhookEventOutstanding, webhookEventState } from "../data/webhookEvent.js";
7
7
  import { PAYMENTS_SYNC_CURSORS_TABLE, PAYMENTS_WEBHOOK_EVENTS_TABLE, paymentsDatabase } from "../data/tables.js";
8
8
  import { fulfillPurchase } from "../grants/apply.js";
9
9
  import { linkProviderAccount, resolveNotificationOwner } from "../projection/owner.js";
10
+ import { notificationTargets } from "../projection/targets.js";
10
11
  import { projectPurchase } from "../projection/writer.js";
11
12
  import { repairOrphanedEvents } from "../projection/orphans.js";
12
13
  import { noteIsRepairable, noteText } from "../rails/contract.js";
@@ -116,10 +117,11 @@ async function record(d1, eventId, payload, now, newId) {
116
117
  * it, so "handled" is tempting — but the guard reads this column, and the event's repair is precisely the
117
118
  * redelivery that follows the missing link. See {@link abandon} and the module doc.
118
119
  */
119
- async function complete(d1, id, now, note) {
120
+ async function complete(d1, id, now, finished) {
120
121
  await withD1Retry(() => paymentsDatabase(d1).updateTable(PAYMENTS_WEBHOOK_EVENTS_TABLE).set({
121
122
  processedAt: now.getTime(),
122
- error: note ?? null
123
+ error: "note" in finished ? finished.note ?? null : null,
124
+ projectedTargets: encodeWebhookEventTargets("targets" in finished ? finished.targets : NO_WEBHOOK_EVENT_TARGETS)
123
125
  }).where("id", "=", id).execute());
124
126
  }
125
127
  /**
@@ -141,8 +143,11 @@ async function fail(d1, id, attempt, error) {
141
143
  attempts: attempt
142
144
  }).where("id", "=", id).execute());
143
145
  }
144
- /** The word an operator greps `error` for. One string, so the writer and a runbook cannot drift apart. */
145
- const QUARANTINED = "quarantined";
146
+ /**
147
+ * The word an operator greps `error` for. One string, so the writer and a runbook cannot drift apart — and
148
+ * shared through `data/webhookEvent.ts`, because the management read classifies on it (#830).
149
+ */
150
+ const QUARANTINED = WEBHOOK_EVENT_QUARANTINED;
146
151
  /**
147
152
  * The word for the other reason this sweep walks away from an event, likewise greppable.
148
153
  *
@@ -368,7 +373,7 @@ async function sweepPaddle(deps) {
368
373
  return report;
369
374
  }
370
375
  report.ignored += 1;
371
- await complete(deps.d1, id, at, noteText(notification.note));
376
+ await complete(deps.d1, id, at, { note: noteText(notification.note) });
372
377
  cursor = event.eventId;
373
378
  continue;
374
379
  }
@@ -399,20 +404,26 @@ async function sweepPaddle(deps) {
399
404
  environment: deps.environment,
400
405
  now: at
401
406
  });
402
- if (notification.stateEvent) await projectPurchase(deps.d1, {
407
+ const standing = notification.stateEvent ? await projectPurchase(deps.d1, {
403
408
  ...notification.stateEvent,
404
409
  ...subject
405
410
  }, {
406
411
  config: deps.config,
407
412
  environment: deps.environment,
408
413
  now: at
409
- });
414
+ }) : void 0;
410
415
  await (deps.fulfill ?? ((d1, value) => fulfillPurchase(d1, value, {
411
416
  config: deps.config,
412
417
  ledgerPeer: deps.ledgerPeer,
413
418
  now: () => at.getTime()
414
419
  })))(deps.d1, projection);
415
- await complete(deps.d1, id, at);
420
+ await complete(deps.d1, id, at, { targets: notificationTargets({
421
+ event: notification.event,
422
+ projection
423
+ }, {
424
+ event: notification.stateEvent,
425
+ projection: standing
426
+ }) });
416
427
  report.projected += 1;
417
428
  cursor = event.eventId;
418
429
  } catch (cause) {
@@ -117,7 +117,7 @@ Worth knowing, because it explains the failure modes:
117
117
  3. Lemon Squeezy takes the money as merchant of record and POSTs its webhook. The echoed `pithy_account_reference` and the delivery's `customer_id` are what write the `(lemonSqueezy, <customer id>) → subject` row. **This is the only place that link is ever made**, because this rail has no client-submission path at all. A reference that is not exactly that encoding decodes to nobody — a bare id, the format that predates subjects, is refused rather than read as a user — and the delivery lands unbound.
118
118
  4. Every delivery's `X-Signature` is verified — an HMAC over the exact received bytes — then recorded, then projected. There is no timestamp in the scheme and so **no freshness window**: replay protection is entirely the `UNIQUE (rail, providerEventId)` insert, with the projection's monotonic `providerEventAt` rule behind it.
119
119
  5. An invoice-domain delivery costs one read. A subscription invoice carries no variant, and the writer needs one, so the rail reads the invoice's subscription to learn which variant it bills. Subscription and order deliveries carry everything they need and cost nothing.
120
- 6. Every delivery lands in `pithy_payments_webhook_events`. A delivery that projected carries `processedAt`; one that did not carries the reason and no `processedAt`, so the store's next attempt — or your replay — runs it again.
120
+ 6. Every delivery lands in `pithy_payments_webhook_events`. A delivery that projected carries `processedAt`; one that did not carries the reason and no `processedAt`, so the store's next attempt — or your replay — runs it again. A management client reads that log — each delivery as projected, pending or abandoned, with the purchase and subscription rows it changed, never its payload — at `GET /payments/admin/webhook-events`, behind `payments:webhooks:read`.
121
121
 
122
122
  So: a delivery that fails its signature is 401 and **nothing is recorded**, which is what stops a forger filling the table. A delivery Lemon Squeezy signed but this build does not map — a license-key event, an affiliate payout — is 200 with a row and nothing else. A test-mode purchase against a production deployment is 200, is not projected, and records `payments/environment_mismatch`. An outage at Lemon Squeezy while an invoice delivery is being read answers `payments/provider_unavailable` (503) rather than a signature failure, so the store redelivers instead of an operator hunting for a rotated key.
123
123
 
package/docs/paddle.md CHANGED
@@ -401,6 +401,8 @@ Build it with `bun run build` in `@pithy-sh/payments`; the artifact is `dist/pad
401
401
  | `inline` | An iframe rendered into an element of yours. Looks like part of the app. |
402
402
  | `hosted` | A redirect to Paddle's own page. Needs a default payment link on the account. |
403
403
 
404
+ **A React Native app sells Paddle in `hosted` mode only.** An overlay or an inline frame opens inside a web page, and a phone has none to open it in, so the scaffolded paywall answers the other two with a refusal that names the config line to change. In `hosted` the checkout opens in the system browser, and the app reads the subscription again once the reader is back.
405
+
404
406
  `POST /payments/checkout` answers `{ kind: "paddle", transactionId, clientToken, environment, displayMode, successUrl }` in the first two, and the ordinary `{ kind: "redirect", url }` in the third. Nothing on that response is secret: the client token is publishable exactly as a Stripe price id is, and the API key and the signing secret are not expressible on it.
405
407
 
406
408
  The screens are wired for you. `useCheckout().handoff` carries it, `usePaddleCheckout(handoff, { frameTarget })` opens it, and the scaffolded `paywall.tsx` and `pricing.tsx` render the container from `opened.inline` — so switching `overlay` to `inline` in your config needs no edit to a scaffolded file.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pithy-sh/payments",
3
- "version": "0.6.1",
3
+ "version": "0.7.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -42,9 +42,10 @@
42
42
  "@paddle/paddle-js": "^1.6.4"
43
43
  },
44
44
  "peerDependencies": {
45
- "@pithy-sh/core": "^0.13.0",
46
- "@pithy-sh/ledger": "^0.5.1",
47
- "@pithy-sh/secrets": "^0.6.1",
45
+ "@pithy-sh/core": "^0.14.0",
46
+ "@pithy-sh/ledger": "^0.6.0",
47
+ "@pithy-sh/secrets": "^0.6.2",
48
+ "@pithy-sh/ui-core": "^0.1.0",
48
49
  "hono": "^4.13.2",
49
50
  "kysely": "^0.29.0",
50
51
  "react": "^19.0.0",
@@ -64,6 +65,7 @@
64
65
  "@pithy-sh/ledger": "workspace:*",
65
66
  "@pithy-sh/secrets": "workspace:*",
66
67
  "@pithy-sh/tsconfig": "workspace:*",
68
+ "@pithy-sh/ui-core": "workspace:*",
67
69
  "@types/node": "^22.15.0",
68
70
  "@types/react": "^19.2.17",
69
71
  "@types/react-dom": "^19.2.3",