@pithy-sh/payments 0.3.6 → 0.3.7

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 (42) hide show
  1. package/dist/capability.d.ts +11 -3
  2. package/dist/capability.d.ts.map +1 -1
  3. package/dist/capability.js +33 -8
  4. package/dist/grants/apply.d.ts +11 -5
  5. package/dist/grants/apply.d.ts.map +1 -1
  6. package/dist/grants/apply.js +9 -6
  7. package/dist/grants/ledgerSeam.d.ts +34 -14
  8. package/dist/grants/ledgerSeam.d.ts.map +1 -1
  9. package/dist/grants/ledgerSeam.js +8 -16
  10. package/dist/http/routes.d.ts +8 -0
  11. package/dist/http/routes.d.ts.map +1 -1
  12. package/dist/http/routes.js +9 -8
  13. package/dist/index.d.ts +1 -1
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/peer.d.ts +78 -0
  16. package/dist/peer.d.ts.map +1 -0
  17. package/dist/peer.js +27 -0
  18. package/dist/version.generated.d.ts +1 -1
  19. package/dist/version.generated.js +1 -1
  20. package/dist/workflows/hostPeers.d.ts +37 -0
  21. package/dist/workflows/hostPeers.d.ts.map +1 -0
  22. package/dist/workflows/hostPeers.js +17 -0
  23. package/dist/workflows/paddleSweep.d.ts +3 -0
  24. package/dist/workflows/paddleSweep.d.ts.map +1 -1
  25. package/dist/workflows/paddleSweep.js +2 -0
  26. package/dist/workflows/reconcile.d.ts +6 -0
  27. package/dist/workflows/reconcile.d.ts.map +1 -1
  28. package/dist/workflows/reconcile.js +1 -0
  29. package/dist/workflows/worker.d.ts.map +1 -1
  30. package/dist/workflows/worker.js +3 -0
  31. package/package.json +2 -2
  32. package/src/capability.ts +60 -16
  33. package/src/grants/apply.ts +14 -8
  34. package/src/grants/ledgerSeam.ts +43 -33
  35. package/src/http/routes.ts +17 -8
  36. package/src/index.ts +2 -1
  37. package/src/peer.ts +29 -0
  38. package/src/version.generated.ts +1 -1
  39. package/src/workflows/hostPeers.ts +41 -0
  40. package/src/workflows/paddleSweep.ts +9 -2
  41. package/src/workflows/reconcile.ts +12 -1
  42. package/src/workflows/worker.ts +5 -0
@@ -0,0 +1,37 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { PaymentsLedgerPeer } from "../grants/ledgerSeam";
4
+ /**
5
+ * **The reconcile host's composition: the optional peers it was handed** (#645).
6
+ *
7
+ * An app Worker composes capabilities and `payments()`'s `compose` hook finds the ledger among them. This host
8
+ * composes nothing — it is a prebuilt Worker the adopter never authors — so it has no hook and nothing to find
9
+ * a ledger in. It still owes a credit when a pass repairs a purchase whose product has a `grants.ledger`
10
+ * clause, and it may not import `@pithy-sh/ledger` to make one, for the reason `grants/ledgerSeam.ts` gives.
11
+ *
12
+ * So `pithy` hands it over. When the project's catalog credits a balance, the CLI deploys this host from an
13
+ * entry it generates beside the resolved config, which imports the ledger's `ledgerPeer` from the project's
14
+ * own install and calls {@link providePeers} before re-exporting `worker.ts` unchanged. A catalog that credits
15
+ * nothing gets no entry: `main` stays `worker.ts`, and the bundle never meets the specifier.
16
+ *
17
+ * Its own module rather than an export of `worker.ts`, because every export of a Worker's main module is read
18
+ * as an entrypoint, and a function is not one.
19
+ */
20
+ /** What this host may be handed, keyed by the capability that supplies it. */
21
+ export interface PaymentsHostPeers {
22
+ /** `ledger()`'s peer surface, when the catalog credits a balance. */
23
+ readonly ledger?: PaymentsLedgerPeer;
24
+ }
25
+ /**
26
+ * The peers this host was handed — empty when its entry handed none.
27
+ *
28
+ * A value rather than a getter, and read as a property inside a Workflow's `run`: it is set once, by the entry,
29
+ * before the isolate serves anything, so every replay of a run reads the same thing — which is what
30
+ * `workflowDeterminism.test.ts` holds every driver body to.
31
+ */
32
+ export declare const hostPeers: {
33
+ -readonly [Key in keyof PaymentsHostPeers]: PaymentsHostPeers[Key];
34
+ };
35
+ /** Hand this host its peers. Called once, by the generated entry, before any request or cron fire. */
36
+ export declare function providePeers(peers: PaymentsHostPeers): void;
37
+ //# sourceMappingURL=hostPeers.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hostPeers.d.ts","sourceRoot":"","sources":["../../src/workflows/hostPeers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAC;CACtC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,EAAE;IAAE,CAAC,UAAU,GAAG,IAAI,MAAM,iBAAiB,GAAG,iBAAiB,CAAC,GAAG,CAAC;CAAO,CAAC;AAEpG,sGAAsG;AACtG,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAE3D"}
@@ -0,0 +1,17 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ //#region src/workflows/hostPeers.ts
4
+ /**
5
+ * The peers this host was handed — empty when its entry handed none.
6
+ *
7
+ * A value rather than a getter, and read as a property inside a Workflow's `run`: it is set once, by the entry,
8
+ * before the isolate serves anything, so every replay of a run reads the same thing — which is what
9
+ * `workflowDeterminism.test.ts` holds every driver body to.
10
+ */
11
+ const hostPeers = {};
12
+ /** Hand this host its peers. Called once, by the generated entry, before any request or cron fire. */
13
+ function providePeers(peers) {
14
+ Object.assign(hostPeers, peers);
15
+ }
16
+ //#endregion
17
+ export { hostPeers, providePeers };
@@ -4,6 +4,7 @@ import type { D1Database } from "@cloudflare/workers-types";
4
4
  import type { PaymentsConfig } from "../config/config";
5
5
  import type { PurchaseEnvironment } from "../data/purchase";
6
6
  import { fulfillPurchase } from "../grants/apply";
7
+ import type { PaymentsLedgerPeer } from "../grants/ledgerSeam";
7
8
  import { type PaddleEnvironment, type PaddleHttpFetch } from "../rails/paddle/api";
8
9
  import { PADDLE_EVENT_RETENTION_DAYS } from "../rails/paddle/events";
9
10
  import type { PaymentsPaddleCredentials } from "../secret/registry";
@@ -106,6 +107,8 @@ export interface PaddleSweepDeps {
106
107
  transport?: PaddleHttpFetch;
107
108
  /** Fulfillment for a swept purchase. Defaults to {@link fulfillPurchase}, and is safe to repeat. */
108
109
  fulfill?: (d1: D1Database, projection: Parameters<typeof fulfillPurchase>[1]) => Promise<unknown>;
110
+ /** The ledger the default {@link fulfill} credits through, when the host was handed one. See `grants/ledgerSeam.ts`. */
111
+ ledgerPeer?: PaymentsLedgerPeer;
109
112
  /** How many pages one sweep may walk. A bound on the work, so a first pass finishes. */
110
113
  maxPages?: number;
111
114
  }
@@ -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;AAKlD,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,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;AAiT3C;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAiNnF;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;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"}
@@ -255,6 +255,7 @@ async function repairOrphans(deps, at) {
255
255
  fulfill: async (projection) => {
256
256
  await (deps.fulfill ?? ((d1, value) => fulfillPurchase(d1, value, {
257
257
  config: deps.config,
258
+ ledgerPeer: deps.ledgerPeer,
258
259
  now: () => at.getTime()
259
260
  })))(deps.d1, projection);
260
261
  }
@@ -408,6 +409,7 @@ async function sweepPaddle(deps) {
408
409
  });
409
410
  await (deps.fulfill ?? ((d1, value) => fulfillPurchase(d1, value, {
410
411
  config: deps.config,
412
+ ledgerPeer: deps.ledgerPeer,
411
413
  now: () => at.getTime()
412
414
  })))(deps.d1, projection);
413
415
  await complete(deps.d1, id, at);
@@ -4,6 +4,7 @@ import type { D1Database } from "@cloudflare/workers-types";
4
4
  import { type AuditEmit } from "@pithy-sh/core/src/audit/recorder";
5
5
  import type { PaymentsConfig } from "../config/config";
6
6
  import { type PurchaseEnvironment } from "../data/purchase";
7
+ import type { PaymentsLedgerPeer } from "../grants/ledgerSeam";
7
8
  import type { PurchaseProjection } from "../projection/writer";
8
9
  import type { PaddleSweepReport } from "./paddleSweep";
9
10
  import type { ReconcileRailAccess } from "./railAccess";
@@ -104,6 +105,11 @@ export interface ReconcileDeps {
104
105
  * the webhook already applied is a no-op rather than a double.
105
106
  */
106
107
  fulfill?: (projection: PurchaseProjection) => Promise<unknown>;
108
+ /**
109
+ * The ledger the default {@link fulfill} credits through — handed to the host by the entry `pithy` generates
110
+ * when the catalog credits a balance, and undefined otherwise. Never imported here: see `grants/ledgerSeam.ts`.
111
+ */
112
+ ledgerPeer?: PaymentsLedgerPeer;
107
113
  /**
108
114
  * The Paddle events sweep, or undefined to skip it.
109
115
  *
@@ -1 +1 @@
1
- {"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/workflows/reconcile.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,KAAK,SAAS,EAAY,MAAM,mCAAmC,CAAC;AAI7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAK9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAgE,KAAK,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAErH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH,8GAA8G;AAC9G,MAAM,WAAW,aAAa;IAC5B,+FAA+F;IAC/F,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC7D;AAcD,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,EAAE,EAAE,UAAU,CAAC;IACf,iGAAiG;IACjG,MAAM,EAAE,cAAc,CAAC;IACvB,2GAA2G;IAC3G,WAAW,EAAE,mBAAmB,CAAC;IACjC,4FAA4F;IAC5F,UAAU,CAAC,GAAG,EAAE,IAAI,GAAG,mBAAmB,CAAC;IAC3C,iBAAiB;IACjB,GAAG,IAAI,IAAI,CAAC;IACZ,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,kBAAkB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAChD;AAyBD,+BAA+B;AAC/B,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,6GAA6G;IAC7G,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,MAAM,EAAE,OAAO,CAAC;CACjB;AA0PD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,aAAa,EACnB,MAAM,GAAE,uBAA4B,GACnC,OAAO,CAAC,eAAe,CAAC,CAyL1B"}
1
+ {"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/workflows/reconcile.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,KAAK,SAAS,EAAY,MAAM,mCAAmC,CAAC;AAI7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAK9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAgE,KAAK,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAErH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH,8GAA8G;AAC9G,MAAM,WAAW,aAAa;IAC5B,+FAA+F;IAC/F,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC7D;AAcD,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,EAAE,EAAE,UAAU,CAAC;IACf,iGAAiG;IACjG,MAAM,EAAE,cAAc,CAAC;IACvB,2GAA2G;IAC3G,WAAW,EAAE,mBAAmB,CAAC;IACjC,4FAA4F;IAC5F,UAAU,CAAC,GAAG,EAAE,IAAI,GAAG,mBAAmB,CAAC;IAC3C,iBAAiB;IACjB,GAAG,IAAI,IAAI,CAAC;IACZ,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,kBAAkB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D;;;OAGG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAChD;AAyBD,+BAA+B;AAC/B,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,6GAA6G;IAC7G,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,MAAM,EAAE,OAAO,CAAC;CACjB;AA+PD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,aAAa,EACnB,MAAM,GAAE,uBAA4B,GACnC,OAAO,CAAC,eAAe,CAAC,CAyL1B"}
@@ -148,6 +148,7 @@ async function reconcileOne(deps, runId, access, purchase, now, dryRun) {
148
148
  const fulfill = deps.fulfill ?? ((repaired) => fulfillPurchase(deps.d1, repaired, {
149
149
  config: deps.config,
150
150
  emit: deps.emit,
151
+ ledgerPeer: deps.ledgerPeer,
151
152
  now: () => now.getTime()
152
153
  }));
153
154
  try {
@@ -1 +1 @@
1
- {"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/workflows/worker.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAU/F,OAAO,EAAE,KAAK,eAAe,EAAqB,MAAM,aAAa,CAAC;AAGtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,KAAK,iBAAiB,EAAyB,MAAM,gBAAgB,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAiBxD;;;;;;GAMG;AACH,qBAAa,yBAA0B,SAAQ,kBAAkB,CAAC,iBAAiB,EAAE,uBAAuB,CAAC;IAC5F,GAAG,CAAC,KAAK,EAAE,aAAa,CAAC,uBAAuB,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CAmE9G;CACF;;IAGC;;;;;;OAMG;IACG,SAAS,cAAc,OAAO,OAAO,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC"}
1
+ {"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/workflows/worker.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAW/F,OAAO,EAAE,KAAK,eAAe,EAAqB,MAAM,aAAa,CAAC;AAGtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,KAAK,iBAAiB,EAAyB,MAAM,gBAAgB,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAiBxD;;;;;;GAMG;AACH,qBAAa,yBAA0B,SAAQ,kBAAkB,CAAC,iBAAiB,EAAE,uBAAuB,CAAC;IAC5F,GAAG,CAAC,KAAK,EAAE,aAAa,CAAC,uBAAuB,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CAuE9G;CACF;;IAGC;;;;;;OAMG;IACG,SAAS,cAAc,OAAO,OAAO,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC"}
@@ -5,6 +5,7 @@ import { PaymentsReconcileParams } from "./specs.js";
5
5
  import { triggerPaymentsReconcile } from "../http/dispatch.js";
6
6
  import { batchedRailAccess } from "./railAccess.js";
7
7
  import { reconcilePayments } from "./reconcile.js";
8
+ import { hostPeers } from "./hostPeers.js";
8
9
  import { sweepPaddle } from "./paddleSweep.js";
9
10
  import { auditLogEmit, logReconcileReport } from "./report.js";
10
11
  import { paymentsWorkflowRetry } from "./retryPolicy.js";
@@ -54,6 +55,7 @@ var PaymentsReconcileWorkflow = class extends WorkflowEntrypoint {
54
55
  }),
55
56
  now: () => /* @__PURE__ */ new Date(),
56
57
  emit: auditLogEmit(log),
58
+ ledgerPeer: hostPeers.ledger,
57
59
  /**
58
60
  * The Paddle events sweep, supplied only when that rail is on.
59
61
  *
@@ -72,6 +74,7 @@ var PaymentsReconcileWorkflow = class extends WorkflowEntrypoint {
72
74
  credentials: railCredentials(credentials, "paddle"),
73
75
  paddleEnvironment: config.paddle?.environment ?? "sandbox",
74
76
  deployment: this.env.ENVIRONMENT,
77
+ ledgerPeer: hostPeers.ledger,
75
78
  now: () => /* @__PURE__ */ new Date()
76
79
  }) } : {}
77
80
  }, classifiedSteps(step, paymentsWorkflowRetry, NonRetryableError), params);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pithy-sh/payments",
3
- "version": "0.3.6",
3
+ "version": "0.3.7",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -43,7 +43,7 @@
43
43
  },
44
44
  "peerDependencies": {
45
45
  "@pithy-sh/core": "^0.7.4",
46
- "@pithy-sh/ledger": "^0.2.5",
46
+ "@pithy-sh/ledger": "^0.2.6",
47
47
  "@pithy-sh/secrets": "^0.2.7",
48
48
  "hono": "^4.13.2",
49
49
  "kysely": "^0.29.0",
package/src/capability.ts CHANGED
@@ -18,10 +18,12 @@ import { paymentsTables } from "./data/tables";
18
18
  import { installEntitlementResolver } from "./entitlement/resolver";
19
19
  import type { PaymentsSubjectResolver, PaymentsSubjectSeam } from "./entitlement/subjectSeam";
20
20
  import { requireImplementedSubject } from "./entitlement/unimplementedSubject";
21
+ import type { PaymentsLedgerPeer } from "./grants/ledgerSeam";
21
22
  import { paymentsManifestConfig } from "./http/manifestConfig";
22
23
  import { registerPaymentsRoutes } from "./http/routes";
23
24
  import { paymentsAdminRoutes } from "./http/scopes";
24
25
  import { payments_0001_purchases } from "./migrations/0001_purchases";
26
+ import { type PaymentsPeer, paymentsPeer } from "./peer";
25
27
  import { paymentsInapplicableSecrets, paymentsSecretBranches } from "./secret/branches";
26
28
  import { paymentsSecretsRegistry } from "./secret/registry";
27
29
  import { paymentsExampleSeed } from "./seeds/example";
@@ -67,23 +69,41 @@ export type PaymentsOptions = PaymentsConfigInput & {
67
69
  };
68
70
 
69
71
  /**
70
- * The slice of `@pithy-sh/ledger`'s capability the grants check reads — its declared currency codes.
72
+ * The slice of `@pithy-sh/ledger`'s capability payments reads — its declared currency codes, and the peer
73
+ * surface a credit goes through.
71
74
  *
72
75
  * Structural, and recognized by a copied three-line predicate rather than by importing the ledger's own
73
- * `isLedgerCapability`. Two reasons, and both are binding. `compose` is **synchronous**, so the guarded
74
- * dynamic import that keeps the ledger optional everywhere else is not available here. And a static import
75
- * would make an optional peer a hard one for every project, including the great majority whose catalogs sell
76
- * features and never name a currency. This is the same trade `guards.ts` documents for `requireAuth`.
76
+ * `isLedgerCapability`. The ledger is an **optional** peer, and a specifier naming it — static, or a dynamic
77
+ * `import()` behind a `try` — is one a bundler resolves whether or not the branch holding it ever runs, so a
78
+ * project that never installed it could not bundle payments at all (#645). So payments names the package
79
+ * nowhere, not even for a type, and the ledger reaches it through the composition: this hook finds it, and
80
+ * {@link payments} keeps its `ledgerPeer` for the routes.
81
+ *
82
+ * `ledgerPeer` is optional here because a ledger released before #645 does not carry one, and that is a
83
+ * composition {@link checkLedgerGrants} refuses by name rather than a purchase that fails later.
77
84
  */
78
- interface LedgerPeer extends Capability {
85
+ interface LedgerPeerCapability extends Capability {
79
86
  ledgerConfig: { currencies: readonly { code: string }[] };
87
+ ledgerPeer?: PaymentsLedgerPeer;
80
88
  }
81
89
 
82
90
  /** Whether a composed capability is the ledger, carrying its parsed currency set. */
83
- function isLedgerPeer(capability: Capability): capability is LedgerPeer {
91
+ function isLedgerPeer(capability: Capability): capability is LedgerPeerCapability {
84
92
  return capability.name === "ledger" && "ledgerConfig" in capability;
85
93
  }
86
94
 
95
+ /** The ledger's peer surface among the composed capabilities, or undefined when no ledger is composed. */
96
+ function composedLedger(capabilities: readonly Capability[]): PaymentsLedgerPeer | undefined {
97
+ return capabilities.find(isLedgerPeer)?.ledgerPeer;
98
+ }
99
+
100
+ /** Products named for a sentence: `product "coins_100"`, or `products "a" and "b"`. */
101
+ function products(list: readonly { id: string }[]): string {
102
+ const ids = list.map((entry) => `"${entry.id}"`);
103
+ if (ids.length === 1) return `product ${ids[0]}`;
104
+ return `products ${ids.slice(0, -1).join(", ")} and ${ids[ids.length - 1]}`;
105
+ }
106
+
87
107
  /**
88
108
  * Validate every `grants.currency` against the composed ledger, at assembly.
89
109
  *
@@ -122,11 +142,20 @@ function checkLedgerGrants({ capabilities }: CapabilityComposeContext, config: P
122
142
  const peer = capabilities.find(isLedgerPeer);
123
143
  if (!peer) {
124
144
  throw new ValidationError({
125
- message: "This catalog credits a balance, and no ledger is composed.",
126
- action: "Add `ledger(...)` to this Worker's capabilities, or drop the `grants` clause from the product.",
145
+ message: `No ledger is composed in this Worker, and ${products(granting)} ${granting.length === 1 ? "credits" : "credit"} a balance through one.`,
146
+ action: `Compose \`ledger(...)\` in this Worker, or turn crediting off by removing the \`grants.ledger\` clause from ${products(granting)}.`,
127
147
  detail: `Products with a \`grants.ledger\` clause: ${granting.map((entry) => entry.id).join(", ")}. Crediting needs @pithy-sh/ledger composed in the same Worker.`,
128
148
  });
129
149
  }
150
+ // A ledger from before #645 is composed and cannot be called: it carries no peer surface, and payments no
151
+ // longer imports the package to reach around it. Refused here, by name, rather than as the first purchase.
152
+ if (typeof peer.ledgerPeer?.openLedger !== "function") {
153
+ throw new ValidationError({
154
+ message: "The composed ledger is too old for payments to credit a balance.",
155
+ action: "Upgrade @pithy-sh/ledger to the version this @pithy-sh/payments peers.",
156
+ detail: `The composed ledger capability carries no \`ledgerPeer\`. Products with a \`grants.ledger\` clause: ${granting.map((entry) => entry.id).join(", ")}.`,
157
+ });
158
+ }
130
159
 
131
160
  const declared = new Set(peer.ledgerConfig.currencies.map((currency) => currency.code));
132
161
  const unknown = granting.filter((entry) => !declared.has(entry.currency));
@@ -267,6 +296,12 @@ export interface PaymentsCapability
267
296
  extends Capability<DatabaseSpecMap, KvNamespaceSpecMap, "payments", typeof paymentsWorkflows> {
268
297
  /** The resolved catalog. */
269
298
  paymentsConfig: PaymentsConfig;
299
+ /**
300
+ * What a capability composed beside this one reads purchases through — `support`, showing an operator what a
301
+ * sender bought. Found in its `compose` hook, so it never imports this package and a project without
302
+ * payments bundles it (#645). See `peer.ts`.
303
+ */
304
+ paymentsPeer: PaymentsPeer;
270
305
  }
271
306
 
272
307
  /**
@@ -285,9 +320,10 @@ export interface PaymentsCapability
285
320
  * registry, so a project composing payments without `@pithy-sh/secrets` must fail at assembly rather
286
321
  * than at the first receipt. Auth is *not* listed — it is a seam: under `billingSubject: "user"` a purchase
287
322
  * scopes to the authenticated caller, so with no auth capability composed every route denies, which is the
288
- * right failure and needs no dependency edge. `@pithy-sh/ledger` is likewise a seam, reached through one
289
- * guarded dynamic import and only for products whose catalog entry declares `grants`. Both belong in the
290
- * manifest's `optionalCapabilities`.
323
+ * right failure and needs no dependency edge. `@pithy-sh/ledger` is likewise a seam: `compose` finds it among
324
+ * the composed capabilities and hands its `ledgerPeer` to the routes, and nothing in this package imports it
325
+ * (#645). Only a product whose catalog entry declares `grants` ever calls it. Both belong in the manifest's
326
+ * `optionalCapabilities`.
291
327
  *
292
328
  * Under `billingSubject: "organization"` the holder is not the caller and cannot be derived from them, so
293
329
  * the adopter supplies `resolveSubject` and a composition without one is refused outright — see
@@ -321,6 +357,10 @@ export function payments(options: PaymentsOptions): PaymentsCapability {
321
357
  ...(resolveSubject ? { resolveSubject } : {}),
322
358
  };
323
359
 
360
+ // The optional peers, filled once by `compose` — which runs after this factory, so the routes are handed
361
+ // the slot and read it per request rather than being handed a value that does not exist yet.
362
+ const peers: { ledger: PaymentsLedgerPeer | undefined } = { ledger: undefined };
363
+
324
364
  const migrations: Record<string, Migration> = {
325
365
  "0001_purchases": payments_0001_purchases,
326
366
  };
@@ -357,8 +397,12 @@ export function payments(options: PaymentsOptions): PaymentsCapability {
357
397
  // binding and types `c.var.workflows.trigger("payments/reconcile", …)` precisely.
358
398
  workflows: paymentsWorkflows,
359
399
  // The one thing this capability cannot check on its own: whether the ledger it credits agrees the
360
- // currency exists. See `checkLedgerGrants` for why the failure is otherwise invisible.
361
- compose: (context) => checkLedgerGrants(context, resolved),
400
+ // currency exists. See `checkLedgerGrants` for why the failure is otherwise invisible. And the one place
401
+ // the ledger reaches payments at all: found among the composed capabilities, never imported (#645).
402
+ compose: (context) => {
403
+ checkLedgerGrants(context, resolved);
404
+ peers.ledger = composedLedger(context.capabilities);
405
+ },
362
406
  // The other half of {@link requireResolvableSubject}, and it is at the entrypoint rather than at
363
407
  // composition on purpose: `pithy add` scaffolds an unimplemented `resolveSubject`, and every `pithy`
364
408
  // command evaluates this config to learn what the Worker composes. Refusing here refuses the Worker
@@ -390,11 +434,11 @@ export function payments(options: PaymentsOptions): PaymentsCapability {
390
434
  manifestConfig: paymentsManifestConfig(resolved.billingSubject),
391
435
  // The routes ask the same question the gate does — a checkout, a restore and a portal all need a holder
392
436
  // to key a row to — so they are handed the same seam rather than building one from the config alone.
393
- routes: registerPaymentsRoutes({ config: resolved, subject }),
437
+ routes: registerPaymentsRoutes({ config: resolved, subject, ledger: () => peers.ledger }),
394
438
  seeds: [paymentsExampleSeed],
395
439
  });
396
440
 
397
- return Object.assign(capability, { paymentsConfig: resolved });
441
+ return Object.assign(capability, { paymentsConfig: resolved, paymentsPeer });
398
442
  }
399
443
 
400
444
  /** Whether a capability is the payments capability — carries its resolved catalog. */
@@ -9,13 +9,13 @@ import type { PaymentsPurchase } from "../data/purchase";
9
9
  import type { PurchaseStatus } from "../data/status";
10
10
  import type { PurchaseProjection } from "../projection/writer";
11
11
  import { type ClawbackOutcome, clawbackGrants } from "./clawback";
12
- import { ledgerAccountId, openPaymentsLedger, type PaymentsLedger } from "./ledgerSeam";
12
+ import { ledgerAccountId, openPaymentsLedger, type PaymentsLedger, type PaymentsLedgerPeer } from "./ledgerSeam";
13
13
 
14
14
  /**
15
15
  * Fulfillment: turning a projected purchase into the balance a `grants` clause promised.
16
16
  *
17
- * This is deliberately **not** in the projection writer. The writer stays pure D1 so its tests resolve no
18
- * optional package, and the credit is a separate step its caller runs on what it returned — a route, or any
17
+ * This is deliberately **not** in the projection writer. The writer stays pure D1 so its tests need no ledger,
18
+ * and the credit is a separate step its caller runs on what it returned — a route, or any
19
19
  * other caller holding a projection. Nothing is lost by the separation, because the credit's idempotency has
20
20
  * never rested on call ordering: it rests on the ledger's `UNIQUE (ref)`.
21
21
  *
@@ -93,8 +93,14 @@ export interface GrantOptions {
93
93
  export interface FulfillPurchaseOptions extends GrantOptions {
94
94
  /** The audit seam. Defaults to core's no-op, so a caller with no recorder composed needs no branch. */
95
95
  emit?: AuditEmit;
96
- /** An already-open ledger. Absent in production — the guarded import supplies one only when it is needed. */
96
+ /** An already-open ledger. Absent in production, where {@link ledgerPeer} opens one only when it is needed. */
97
97
  ledger?: PaymentsLedger;
98
+ /**
99
+ * The ledger the composition handed over — `ledger()`'s `ledgerPeer`, found by `payments()`'s `compose` hook,
100
+ * or handed to the reconcile host by its generated entry. Undefined when no ledger is composed, which is
101
+ * only a fault for a product that credits one.
102
+ */
103
+ ledgerPeer?: PaymentsLedgerPeer;
98
104
  /** The clock the ledger stamps its rows with. Injected so a fulfillment is deterministic under test. */
99
105
  now?: () => number;
100
106
  }
@@ -156,9 +162,9 @@ export async function applyGrants(
156
162
  * Fulfill one projected purchase in both directions: credit what it bought, and reverse what a refund took
157
163
  * back where the catalog asks for it.
158
164
  *
159
- * The ledger is opened **lazily, and only when the catalog names a currency**. That laziness is the whole
160
- * reason the optional peer stays optional: a project selling nothing but features never resolves the import,
161
- * so it neither installs `@pithy-sh/ledger` nor carries it in a Worker bundle.
165
+ * The ledger is opened **only when the catalog names a currency**, and only from what the composition handed
166
+ * over. A project selling nothing but features never composes one, never installs `@pithy-sh/ledger`, and —
167
+ * because nothing here names the package — never carries a specifier a bundler would have to resolve (#645).
162
168
  *
163
169
  * A refused clawback is recorded here rather than thrown. It is the one fulfillment fact no other table
164
170
  * holds — a successful credit or debit is already a ledger row, keyed by a ref that names the purchase — so
@@ -172,7 +178,7 @@ export async function fulfillPurchase(
172
178
  const { purchase } = projection;
173
179
  if (ledgerGrantFor(options.config, purchase.productId) === undefined) return { granted: [], clawedBack: [] };
174
180
 
175
- const ledger = options.ledger ?? (await openPaymentsLedger(d1, { now: options.now }));
181
+ const ledger = options.ledger ?? openPaymentsLedger(d1, { peer: options.ledgerPeer, now: options.now });
176
182
  const granted = await applyGrants(ledger, projection, options);
177
183
  const clawedBack = await clawbackGrants(ledger, projection, options);
178
184
 
@@ -6,19 +6,30 @@ import { InternalError } from "@pithy-sh/core/src/error/pithyError";
6
6
  import { encodeSubjectReference, type PaymentsSubject } from "../data/subject";
7
7
 
8
8
  /**
9
- * The single point of contact between `@pithy-sh/payments` and `@pithy-sh/ledger`.
9
+ * The single point of contact between `@pithy-sh/payments` and `@pithy-sh/ledger` — and it imports nothing
10
+ * from it.
10
11
  *
11
12
  * The ledger is an **optional peer**: most catalogs sell features, not currency, and a project that never
12
- * declares a `grants` clause must neither install the package nor pay for it in its Worker bundle. So the
13
- * import is dynamic and it lives in exactly one file — grep `@pithy-sh/ledger` in this package and you find
14
- * this line and nothing else. Everything downstream depends on {@link PaymentsLedger}, a structural
15
- * two-method view, which is also what keeps the grant modules testable without resolving an optional package.
13
+ * declares a `grants` clause must neither install the package nor carry it in a Worker bundle. This file used
14
+ * to reach it with `import("@pithy-sh/ledger/src/ledger")` behind a `try`, which is optional at runtime and
15
+ * required at bundle time — wrangler's esbuild resolves a literal specifier whether or not the branch holding
16
+ * it ever runs, so every project composing payments without the ledger could not deploy its payments host at
17
+ * all (#645). The unit test here injected a loader, so it proved the runtime half and never met the bundler.
18
+ *
19
+ * **So the ledger is handed to payments, never fetched by it.** `ledger()` carries its peer surface as
20
+ * `ledgerPeer`; `payments()`'s `compose` hook finds it among the composed capabilities and keeps it for the
21
+ * routes, and the reconcile host — which composes nothing — is handed it by the entry `pithy` generates when
22
+ * the catalog credits a balance. Everything downstream depends on {@link PaymentsLedgerPeer} and
23
+ * {@link PaymentsLedger}, structural views, so no module in this package names `@pithy-sh/ledger` at all —
24
+ * not even for a type, which would put an optional package on the typecheck path of every module that touches
25
+ * fulfillment. `optionalPeerImports.test.ts` holds the whole kit to that.
16
26
  *
17
27
  * **An absent ledger is an error, never a skip.** A catalog with a `grants` clause has told us a purchase
18
28
  * credits a balance; quietly not crediting it is a support ticket that arrives weeks later as "I paid and got
19
29
  * no coins". The normal place this is caught is far earlier — `payments()`'s `compose` hook refuses at
20
30
  * assembly when a `grants` product is composed without the ledger, so a deploy fails rather than a purchase.
21
- * This throw is the backstop for a caller that reached fulfillment some other way, and it names the fix.
31
+ * The throw in {@link openPaymentsLedger} is the backstop for a caller that reached fulfillment some other way,
32
+ * and it names the fix.
22
33
  */
23
34
 
24
35
  /**
@@ -95,47 +106,46 @@ export function ledgerAccountId(subject: PaymentsSubject): string {
95
106
  return subject.subjectId;
96
107
  }
97
108
 
98
- /** How the ledger module is reached. Injectable so the absent-package path is a test rather than a hope. */
99
- export type PaymentsLedgerLoader = () => Promise<{
100
- openLedger: (d1: D1Database, now?: () => number) => PaymentsLedger;
101
- }>;
109
+ /** How a ledger is opened over a D1: `@pithy-sh/ledger`'s own `openLedger`, as payments sees it. */
110
+ export type PaymentsLedgerOpener = (d1: D1Database, now?: () => number) => PaymentsLedger;
102
111
 
103
- /** The real loader — the only `@pithy-sh/ledger` import in the package. */
104
- const loadLedgerModule: PaymentsLedgerLoader = () => import("@pithy-sh/ledger/src/ledger");
112
+ /**
113
+ * The slice of `@pithy-sh/ledger`'s peer surface payments calls — its `ledgerPeer`, structurally.
114
+ *
115
+ * Structural for {@link PaymentsLedger}'s reason: a type imported from the optional package would put it on
116
+ * the typecheck path of every module that touches fulfillment. The ledger's own `ledgerPeer` satisfies it, and
117
+ * `capability.test.ts` composes the real one to prove that stays true.
118
+ */
119
+ export interface PaymentsLedgerPeer {
120
+ /** Open the ledger against a D1 binding, stamping rows with `now`. */
121
+ openLedger: PaymentsLedgerOpener;
122
+ }
105
123
 
106
124
  /** What {@link openPaymentsLedger} accepts beyond the binding. */
107
125
  export interface OpenPaymentsLedgerOptions {
108
- /** Override the module loader. Tests only; production always resolves the real package. */
109
- load?: PaymentsLedgerLoader;
126
+ /** The ledger the composition handed over, or undefined when none is composed. */
127
+ peer?: PaymentsLedgerPeer;
110
128
  /** The clock the ledger stamps its rows with. Injected so a fulfillment is deterministic under test. */
111
129
  now?: () => number;
112
130
  }
113
131
 
114
132
  /**
115
- * Open the ledger against the app database, or explain what is missing.
133
+ * Open the ledger the composition handed over against the app database, or explain what is missing.
116
134
  *
117
135
  * The ledger's tables live in the same D1 as payments' own — both capabilities bind `DB` — so there is no
118
136
  * second database to reach and no configuration to resolve. That is also why the two write independently and
119
137
  * a credit is idempotent on its `ref` rather than on being in the purchase's transaction: D1 has no
120
138
  * cross-statement transaction a caller can hold open across two packages.
121
139
  */
122
- export async function openPaymentsLedger(
123
- d1: D1Database,
124
- options: OpenPaymentsLedgerOptions = {},
125
- ): Promise<PaymentsLedger> {
126
- const load = options.load ?? loadLedgerModule;
127
- let module: { openLedger: (d1: D1Database, now?: () => number) => PaymentsLedger };
128
- try {
129
- module = await load();
130
- } catch (cause) {
131
- throw new InternalError(
132
- {
133
- message: "This purchase credits a balance, and the ledger is not installed.",
134
- action: "Install @pithy-sh/ledger and compose ledger(...), or drop the `grants` clause from the product.",
135
- detail: `Loading @pithy-sh/ledger failed: ${cause instanceof Error ? cause.message : String(cause)}`,
136
- },
137
- { cause },
138
- );
140
+ export function openPaymentsLedger(d1: D1Database, options: OpenPaymentsLedgerOptions = {}): PaymentsLedger {
141
+ if (options.peer === undefined) {
142
+ throw new InternalError({
143
+ message: "This purchase credits a balance, and no ledger is composed.",
144
+ action:
145
+ "Add `ledger(...)` to this Worker's capabilities in pithy.config.ts, or drop the `grants` clause from the product.",
146
+ detail:
147
+ "fulfillPurchase reached a product with a grants.ledger clause and was handed no ledger peer. payments() refuses that composition at assembly, so this caller reached fulfillment some other way, or a host was deployed without the entry that hands it the ledger.",
148
+ });
139
149
  }
140
- return module.openLedger(d1, options.now);
150
+ return options.peer.openLedger(d1, options.now);
141
151
  }
@@ -55,6 +55,7 @@ import {
55
55
  PaymentsSubscriptionChangeRefusedError,
56
56
  } from "../error/errors";
57
57
  import { fulfillPurchase } from "../grants/apply";
58
+ import type { PaymentsLedgerPeer } from "../grants/ledgerSeam";
58
59
  import { repairOrphanedEvents } from "../projection/orphans";
59
60
  import { linkProviderAccount, providerAccountForSubject, resolveNotificationOwner } from "../projection/owner";
60
61
  import { resolveEntitlements } from "../projection/resolve";
@@ -333,6 +334,13 @@ export interface PaymentsRoutesOptions {
333
334
  * compose organization billing without a resolver rather than reaching this state.
334
335
  */
335
336
  subject?: PaymentsSubjectSeam;
337
+ /**
338
+ * The ledger a `grants` product credits through, read per request — `payments()` hands the slot its
339
+ * `compose` hook fills, because `compose` runs after this factory. Undefined when no ledger is composed,
340
+ * which `payments()` refuses at assembly for any catalog that credits one. Never imported: see
341
+ * `grants/ledgerSeam.ts`.
342
+ */
343
+ ledger?: () => PaymentsLedgerPeer | undefined;
336
344
  }
337
345
 
338
346
  /** The app `DB` binding, or a wiring failure. Payments cannot resolve anything without it. */
@@ -1254,14 +1262,6 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
1254
1262
  return projection;
1255
1263
  }
1256
1264
 
1257
- /**
1258
- * Credit what the purchase bought, and reverse it where a refund and the catalog both ask.
1259
- *
1260
- * A no-op for every product with no `grants` clause, and it resolves the optional `@pithy-sh/ledger` import
1261
- * only when one is present — so a project selling nothing but features never reaches the package. A failure
1262
- * here is deliberately left to propagate: the credit's ref is stable, so a retry settles it, and swallowing
1263
- * it would lose a purchase's currency with nothing anywhere to read.
1264
- */
1265
1265
  /**
1266
1266
  * Project the orphans a link just made resolvable. Never throws: see {@link repairOrphanedEvents}.
1267
1267
  *
@@ -1291,10 +1291,19 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
1291
1291
  }
1292
1292
  }
1293
1293
 
1294
+ /**
1295
+ * Credit what the purchase bought, and reverse it where a refund and the catalog both ask.
1296
+ *
1297
+ * A no-op for every product with no `grants` clause, and it calls the ledger the composition handed over
1298
+ * only when one is present — so a project selling nothing but features never needs one. A failure here is
1299
+ * deliberately left to propagate: the credit's ref is stable, so a retry settles it, and swallowing it would
1300
+ * lose a purchase's currency with nothing anywhere to read.
1301
+ */
1294
1302
  async function fulfill(c: Context<PithyHonoEnv>, projection: PurchaseProjection): Promise<void> {
1295
1303
  await fulfillPurchase(database(c), projection, {
1296
1304
  config,
1297
1305
  emit: c.var.emit,
1306
+ ledgerPeer: options.ledger?.(),
1298
1307
  now: () => clock().getTime(),
1299
1308
  });
1300
1309
  }
package/src/index.ts CHANGED
@@ -129,7 +129,8 @@ export {
129
129
  type OpenPaymentsLedgerOptions,
130
130
  openPaymentsLedger,
131
131
  type PaymentsLedger,
132
- type PaymentsLedgerLoader,
132
+ type PaymentsLedgerOpener,
133
+ type PaymentsLedgerPeer,
133
134
  } from "./grants/ledgerSeam";
134
135
  export { PAYMENTS_RECONCILE_KEY, triggerPaymentsReconcile } from "./http/dispatch";
135
136
  export { requireAuth } from "./http/guards";
package/src/peer.ts ADDED
@@ -0,0 +1,29 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+
4
+ import { PaymentsPurchase } from "./data/purchase";
5
+ import { PAYMENTS_PURCHASES_TABLE, paymentsDatabase } from "./data/tables";
6
+ import { resolveEntitlements } from "./projection/resolve";
7
+
8
+ /**
9
+ * **What a capability composed beside payments may read — handed to it, never imported by it** (#645).
10
+ *
11
+ * `@pithy-sh/payments` is an optional peer of `support`, which shows an operator what a sender bought and is
12
+ * entitled to. It used to reach these modules by `import()` behind a `try`, and a literal specifier is one a
13
+ * bundler resolves whether or not the branch holding it ever runs — so a project without payments could not
14
+ * bundle support at all.
15
+ *
16
+ * So `payments()` carries this object as `paymentsPeer`, and a dependent finds it among the composed
17
+ * capabilities in its `compose` hook. The dependent names this package only in a type, which a bundler never
18
+ * sees. Reads only: the purchases table and the schema that decodes it, and the resolver every entitlement
19
+ * gate in the kit already trusts.
20
+ */
21
+ export const paymentsPeer = {
22
+ PAYMENTS_PURCHASES_TABLE,
23
+ paymentsDatabase,
24
+ PaymentsPurchase,
25
+ resolveEntitlements,
26
+ } as const;
27
+
28
+ /** Payments' peer surface, by type — what `paymentsPeer` holds. */
29
+ export type PaymentsPeer = typeof paymentsPeer;
@@ -13,4 +13,4 @@
13
13
  export const PACKAGE_NAME = "@pithy-sh/payments";
14
14
 
15
15
  /** This package's version, stamped from its own package.json at generation time. */
16
- export const PACKAGE_VERSION = "0.3.6";
16
+ export const PACKAGE_VERSION = "0.3.7";